diff --git a/_partials/self-hosted/_scar-migration.mdx b/_partials/self-hosted/_scar-migration.mdx new file mode 100644 index 0000000000..c3cfb5bddb --- /dev/null +++ b/_partials/self-hosted/_scar-migration.mdx @@ -0,0 +1,396 @@ +--- +partial_category: self-hosted +partial_name: scar-migration +--- + +The {props.edition} installation process requires users to configure and maintain an HTTP server to host {props.edition} manifests. This +server is known as the Spectro Cloud Artifact Regisry (SCAR). Alternatively, users now have the option to migrate these +manifests to the same OCI registry that hosts the {props.edition} images and packs. This migration is handled by a service +called Specman, which fetches the manifests from the OCI registry and serves them via an internal HTTP server. + +The migration process involves two main steps: + +- Pushing the {props.edition} manifests to the OCI registry. +- Updating the SCAR endpoint to point to the new internal HTTP server. + +Once the migration is complete, there is no longer a need to maintain a separate file server exclusively for hosting the +{props.edition} manifests. + +This guide will direct you through the steps required to push the {props.edition} manifests to the OCI registry and update the +SCAR endpoint. + +## Prerequisites + +- A deployed self-hosted {props.edition} that uses a customer-managed SCAR to host {props.edition} + manifests. +- Access to the {props.edition} cluster kubeconfig file to verify the SCAR endpoint. + + :::tip + + If you deployed {props.edition} using the Palette CLI, you can download the kubeconfig file from the {props.edition} cluster details + page in the system console. Navigate to the **Enterprise Cluster Migration** page and click on the **Admin + Kubeconfig** link to download the kubeconfig file. If you deployed {props.edition} to an existing Kubernetes cluster, contact + your cluster administrator to obtain the kubeconfig file. For instructions on using the kubeconfig file to access your + cluster, refer to the . + + ::: + +- Access to the file server that hosts the {props.edition} manifests. +- The {props.edition} cluster must have been upgraded to version `4.5.13` or later. This is required for the SCAR migration to + function properly. +- Access to the {props.edition} system console. +- Ensure the following software is installed and available in the environment hosting the file server. For example, if + you deployed an airgapped instance of {props.edition} to VMware using an , these tools must be available on your airgap support VM. + + - [tar](https://www.gnu.org/software/tar/) + - [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - Required only for AWS + ECR. + - [ORAS](https://oras.land/docs/installation/) v1.0.0 + + :::warning + + This specific version of ORAS is explicitly required for pushing packs to OCI registries. + + ::: + +- Ensure the following software is installed and available locally on your workstation. + - [curl](https://curl.se/docs/install.html) + - [jq](https://jqlang.github.io/jq/download/) + - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) + +## Migrate SCAR + +1. In a terminal with connectivity to your {props.edition} cluster, delete any existing secrets named `spectro-manifest-registry-secrets` in the `hubble-system` namespace. + + ```shell + kubectl delete secret spectro-manifest-registry-secrets --nampespace hubble-system + ``` + + ```text hideClipboard + secret "spectro-manifest-registry-secrets" deleted + ``` + +2. Next, open a terminal window in the environment hosting the file server and navigate to the folder where the {props.edition} + manifests are stored. For example, if you deployed an airgapped instance of {props.edition} to VMware using an , navigate to the `/var/www/html/` + directory. + + ```shell + cd /var/www/html/ + ``` + + Alternatively, if you deployed {props.edition} in an airgapped Kubernetes environment using , navigate to the directory served by the file server you configured. + +3. Compress the folder contents into an archive file called `manifests.tgz`. Issue the following command to create the + archive. + + ```shell + tar -czvf manifests.tgz . + ``` + +4. After compressing the files, authenticate with the OCI registry that hosts the {props.edition} images and packs. + + :::tip + + If you deployed an airgapped instance of {props.edition} to VMware using an , the OCI registry address is provided by the `airgap-setup.sh` script output. Alternatively, if you + deployed {props.edition} to an existing Kubernetes cluster using , contact your cluster administrator for the OCI + registry configuration. + + ::: + + + + + + Use `oras` to log in to your OCI registry. Replace the values below with your environment configuration. For + additional information about CLI flags and examples, check out the + [oras login](https://oras.land/docs/commands/oras_login) documentation. Replace `` with the address + of your Harbor registry without the `https://` prefix, and `` and `` with your + Harbor credentials. + + ```shell + oras login --username --password + ``` + + If you are using a Harbor registry with a self-signed certificate, you must add the `--insecure` flag according to the following example. + + ```shell + oras login --insecure --username --password + ``` + + If the login is successful, you will receive the following confirmation message. + + ```hideClipboard + Login Succeeded + ``` + + + + + + Authenticate to your ECR registry using the `aws ecr get-login-password` command. This command generates an ECR + authorization token, which is then passed to the `oras login` command with `AWS` as username. Replace `` + with the AWS region where your ECR registry is configured, and `` with your AWS account ID. + + ```bash + aws ecr get-login-password --region | oras login --username AWS --password-stdin .dkr.ecr..amazonaws.com + ``` + + If the login is successful, you will receive the following confirmation message. + + ```hideClipboard + Login Succeeded + ``` + + + + + +5. Push the `manifests.tgz` file to your OCI registry. + + + + + Issue the following command to push the `manifests.tgz` file to your Harbor registry. Replace `` with the address of your Harbor registry. + + ```shell + oras push /spectro-packs/spectro-manifests/manifest:0.0.0 manifests.tgz + ``` + + + + + + Issue the following command to push the `manifests.tgz` file to your ECR registry. Replace `` with the AWS region where your ECR registry is configured and `` with your AWS account ID. + + ```shell + oras push .dkr.ecr..amazonaws.com/spectro-packs/spectro-manifests/manifest:0.0.0 manifests.tgz + ``` + + + + + +6. Next, login to the {props.edition} system console and select **Administration** from the left **Main Menu**. + +7. Select the **Pack Registries** tab, click the **three-dot Menu** at the end of the OCI registry row, and then select **Edit**. + +8. Check the **Contains Spectro Manifests** box, click **Validate**, and then click **Confirm**. + + ![View of the 'Contains Spectro Manifests' OCI registry box.](/enterprise-version_system-management_scar-migration.webp) + +9. In a terminal with connectivity to your {props.edition} cluster, issue the following command to verify that the `Specman` + service is fetching the content pushed to the OCI registry in step **5** of this guide, with the tag `0.0.0`. + + ```shell + kubectl logs --namespace hubble-system specman-0 + ``` + + ```text hideClipboard + time="2024-12-06T12:43:14Z" level=info msg="Syncing with OCI repo" + time="2024-12-06T12:43:14Z" level=info msg="tags[4.5.11 4.5.13 0.0.0]" + time="2024-12-06T12:43:14Z" level=info msg="Downloading 0.0.0" + time="2024-12-06T12:43:14Z" level=info msg="tags[4.5.11 4.5.13 0.0.0]" + time="2024-12-06T12:43:14Z" level=info msg="Downloading 0.0.0" + time="2024-12-06T12:43:14Z" level=info msg="listing dir /tmp/0.0.03808764833" + time="2024-12-06T12:43:14Z" level=info msg="filename: manifests.tgz, isDir: false" + time="2024-12-06T12:43:14Z" level=info msg="Persisting 0.0.0" + ``` + +10. The final step to complete the migration involves updating the SCAR endpoint to the internal HTTP server endpoint + that now serves the {props.edition} manifests: `https://specman-service.hubble-system.svc.cluster.local:8443`. Issue the + following command to create the script responsible for updating the endpoint. + + ```shell + cat << 'EOF1' > scar-registry-update.sh + #!/bin/bash + ############################################################################### + # Usage: + # ./ec-scar-registry-update.sh https:// admin + ############################################################################### + # + + set -u + set -x + + export ENDPOINT=$1 + export SYSTEM_ADMIN_USERNAME=$2 + export SYSTEM_ADMIN_PASSWORD=$3 + + export SCAR_ENDPOINT=https://specman-service.hubble-system.svc.cluster.local:8443 + export SCAR_USERNAME= + export SCAR_PASSWORD= + + auth_request() { + cat <` with the address of your {props.edition} instance and + `` with the system administrator password. + + ```shell + ./scar-registry-update.sh admin + ``` + + Consider the following example for reference. + + ```shell hideClipboard + ./scar-registry-update.sh https://example.spectrocloud.com admin examplepassword + ``` + + The following message confirms that the script has completed its tasks. + + ```text hideClipboard + Wait for 5 minutes for the sync process to complete. + ``` + You have now migrated SCAR to the OCI registry that hosts the {props.edition} images and packs. In subsequent releases, the {props.edition} airgap installation binary will handle pushing the new manifest to the OCI registry. + +## Validate + +Use the following steps to verify that the endpoint was updated successfully. + +1. Export your {props.edition} credentials as environment variables. Replace `` with the +address of your {props.edition} cluster and `` with the system administrator password. + + ```shell + export ENDPOINT= + export PASSWORD= + ``` + +2. Log in to the Palette System API using the `/v1/auth/syslogin` endpoint. The response will contain the authentication token that you will use in the next request. + + ```shell + AUTH_TOKEN=$(curl --location "${ENDPOINT}/v1/auth/syslogin" \ + --header 'Content-Type: application/json' \ + --data '{ + "username": "admin", + "password": "'${PASSWORD}'" + }' | jq ."Authorization") + ``` + + :::tip + + If your cluster is using the default self-signed certificate, you can use the `--insecure` flag with the `curl` commands + to bypass the certificate check. + + ::: + +3. Use the `/v1/system/config/scar` endpoint to confirm that the SCAR endpoint has been correctly updated. + + ```shell + curl --location "${ENDPOINT}/v1/system/config/scar" \ + --header "Cookie: Authorization=${AUTH_TOKEN}" + ``` + + The output should contain the updated SCAR endpoint. + + ```text hideClipboard + {"endpoint":"https://specman-service.hubble-system.svc.cluster.local:8443"} + ``` \ No newline at end of file diff --git a/docs/docs-content/enterprise-version/system-management/scar-migration.md b/docs/docs-content/enterprise-version/system-management/scar-migration.md new file mode 100644 index 0000000000..d7dacd64ae --- /dev/null +++ b/docs/docs-content/enterprise-version/system-management/scar-migration.md @@ -0,0 +1,16 @@ +--- +sidebar_label: "Migrate SCAR to OCI Registry" +title: "Migrate Customer-Managed SCAR to OCI Registry" +description: + "Learn how to migrate the Spectro Cloud Artifact Regisry (SCAR) content to the OCI registry used to host packs and + images." +icon: "" +hide_table_of_contents: false +sidebar_position: 125 +tags: ["enterprise", "management", "scar"] +keywords: ["self-hosted", "enterprise"] +--- + +import ScarMigration from "../../../../_partials/self-hosted/_scar-migration.mdx"; + + diff --git a/docs/docs-content/vertex/system-management/scar-migration.md b/docs/docs-content/vertex/system-management/scar-migration.md new file mode 100644 index 0000000000..b42ef7eed9 --- /dev/null +++ b/docs/docs-content/vertex/system-management/scar-migration.md @@ -0,0 +1,16 @@ +--- +sidebar_label: "Migrate SCAR to OCI Registry" +title: "Migrate Customer-Managed SCAR to OCI Registry" +description: + "Learn how to migrate the Spectro Cloud Artifact Regisry (SCAR) content to the OCI registry used to host packs and + images." +icon: "" +hide_table_of_contents: false +sidebar_position: 125 +tags: ["vertex", "management", "scar"] +keywords: ["self-hosted", "vertex"] +--- + +import ScarMigration from "../../../../_partials/self-hosted/_scar-migration.mdx"; + + diff --git a/static/assets/docs/images/enterprise-version_system-management_scar-migration.webp b/static/assets/docs/images/enterprise-version_system-management_scar-migration.webp new file mode 100644 index 0000000000..f0db661997 Binary files /dev/null and b/static/assets/docs/images/enterprise-version_system-management_scar-migration.webp differ