Scar Migration - PEM-6444

_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} <PaletteVertexUrlMapper
+    edition={props.edition}
+    text="cluster"
+    palettePath="/install-palette"
+    vertexPath="/install-palette-vertex"
+  /> 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 <VersionedLink text="Access Cluster with CLI" url="/clusters/cluster-management/palette-webctl"/>.
+
+  :::
+
+- 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 <PaletteVertexUrlMapper
+    edition={props.edition}
+    text="OVA"
+    palettePath="/install-palette/install-on-vmware/airgap-install/environment-setup/vmware-vsphere-airgap-instructions"
+    vertexPath="/install-palette-vertex/install-on-vmware/airgap-install/environment-setup/vmware-vsphere-airgap-instructions"
+  />, 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 <PaletteVertexUrlMapper
+    edition={props.edition}
+    text="OVA"
+    palettePath="/install-palette/install-on-vmware/airgap-install/environment-setup/vmware-vsphere-airgap-instructions"
+    vertexPath="/install-palette-vertex/install-on-vmware/airgap-install/environment-setup/vmware-vsphere-airgap-instructions"
+  />, navigate to the `/var/www/html/`
+    directory.
+
+    ```shell
+    cd /var/www/html/
+    ```
+
+    Alternatively, if you deployed {props.edition} in an airgapped Kubernetes environment using <PaletteVertexUrlMapper
+    edition={props.edition}
+    text="Helm charts"
+    palettePath="/install-palette/install-on-kubernetes/airgap-install/kubernetes-airgap-instructions"
+    vertexPath="/install-palette-vertex/install-on-kubernetes/airgap-install/kubernetes-airgap-instructions"
+  />, 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 <PaletteVertexUrlMapper
+    edition={props.edition}
+    text="OVA"
+    palettePath="/install-palette/install-on-vmware/airgap-install/environment-setup/vmware-vsphere-airgap-instructions"
+    vertexPath="/install-palette-vertex/install-on-vmware/airgap-install/environment-setup/vmware-vsphere-airgap-instructions"
+    />, 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 <PaletteVertexUrlMapper
+    edition={props.edition}
+    text="Helm charts"
+    palettePath="/install-palette/install-on-kubernetes/airgap-install/kubernetes-airgap-instructions"
+    vertexPath="/install-palette-vertex/install-on-kubernetes/airgap-install/kubernetes-airgap-instructions"
+    />, contact your cluster administrator for the OCI
+    registry configuration.
+
+    :::
+
+    <!-- prettier-ignore -->
+    <Tabs groupId="registry">
+    <TabItem label="Harbor" value="Harbor_Registry">
+
+    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 `<harbor-address>` with the address
+    of your Harbor registry without the `https://` prefix, and `<harbor-username>` and `<harbor-password>` with your
+    Harbor credentials.
+
+        ```shell
+        oras login <harbor-address> --username <harbor-username> --password <harbor-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 <harbor-address> --insecure --username <harbor-username> --password <harbor-password>
+        ```
+
+        If the login is successful, you will receive the following confirmation message.
+
+        ```hideClipboard
+        Login Succeeded
+        ```
+
+    <!-- prettier-ignore -->
+    </TabItem>
+    <TabItem label="ECR" value="ECR_Registry">
+
+    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 `<aws-region>`
+    with the AWS region where your ECR registry is configured, and `<aws-account-id>` with your AWS account ID.
+
+        ```bash
+        aws ecr get-login-password --region <aws-region> | oras login --username AWS --password-stdin <aws-account-id>.dkr.ecr.<aws-region>.amazonaws.com
+        ```
+
+        If the login is successful, you will receive the following confirmation message.
+
+        ```hideClipboard
+        Login Succeeded
+        ```
+
+    <!-- prettier-ignore -->
+    </TabItem>
+    </Tabs>
+
+5.  Push the `manifests.tgz` file to your OCI registry.
+    <!-- prettier-ignore -->
+    <Tabs groupId="registry">
+    <TabItem label="Harbor" value="Harbor_Registry">
+
+    Issue the following command to push the `manifests.tgz` file to your Harbor registry. Replace `<harbor-address>` with the address of your Harbor registry.
+
+        ```shell
+        oras push <harbor-address>/spectro-packs/spectro-manifests/manifest:0.0.0 manifests.tgz
+        ```
+
+    <!-- prettier-ignore -->
+    </TabItem>
+    <TabItem label="ECR" value="ECR_Registry">
+
+    Issue the following command to push the `manifests.tgz` file to your ECR registry. Replace `<aws-region>` with the AWS region where your ECR registry is configured and `<aws-account-id>` with your AWS account ID.
+
+        ```shell
+        oras push <aws-account-id>.dkr.ecr.<aws-region>.amazonaws.com/spectro-packs/spectro-manifests/manifest:0.0.0 manifests.tgz
+        ```
+
+    <!-- prettier-ignore -->
+    </TabItem>
+    </Tabs>
+
+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://<PALETTE_URL> admin <SYS_ADMIN_PASSWORD>
+        ###############################################################################
+        #
+
+        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 <<EOF
+        {
+            "username": "${SYSTEM_ADMIN_USERNAME}",
+            "password": "${SYSTEM_ADMIN_PASSWORD}"
+        }
+        EOF
+        }
+
+        scar_request(){
+        cat <<EOF
+        {
+            "endpoint": "${SCAR_ENDPOINT}",
+            "password": "${SCAR_PASSWORD}",
+            "username": "${SCAR_USERNAME}"
+        }
+        EOF
+        }
+
+        get_auth_token() {
+        authtoken=$(curl -k --location --silent --request POST "${ENDPOINT}/v1/auth/syslogin?setCookie=true" \
+            --header 'Content-Type: application/json' \
+            --data "$(auth_request)" | jq ."Authorization")
+        if [[ "${authtoken}" == null ]]; then
+            echo "Error Logging in. Please check the credentials and URL"
+            exit 1
+        fi
+        }
+
+        update_scar_repo() {
+        response=$(curl -k --write-out '%{http_code}' --silent --output /dev/null --location --request PUT "${ENDPOINT}/v1/system/config/scar" \
+            --header 'Content-Type: application/json' \
+            --header 'Accept: application/json' \
+            --header "Cookie: Authorization=${authtoken}" \
+            --data-raw "$(scar_request)")
+        if [[ "${response}" != "204" ]]; then
+            echo "Error: Unable to update the Scar Repo"
+        else
+            echo "Success Setting the Scar Repo. Waiting for a minute to get the changes syncing"
+            sleep 60
+        fi
+        }
+
+        update_instance_type() {
+        response=$(curl -k --write-out '%{http_code}' --location "${ENDPOINT}/v1/jobs/internal/syncCloudInstanceTypesData/run" \
+            --header 'Content-Type: application/json' \
+            --header 'Accept: application/json' \
+            --header "Cookie: Authorization=${authtoken}")
+        if [[ "${response}" != "204" ]]; then
+            echo "Error: Unable to update the Instance Type"
+        else
+            echo "Started Syncing Storage Type from the palette Service"
+        fi
+        }
+
+        update_storage_type() {
+        response=$(curl -k --write-out '%{http_code}' --location "${ENDPOINT}/v1/jobs/internal/syncCloudStorageTypesData/run" \
+            --header 'Content-Type: application/json' \
+            --header 'Accept: application/json' \
+            --header "Cookie: Authorization=${authtoken}")
+        if [[ "${response}" != "204" ]]; then
+            echo "Error: Unable to update the Storage Type"
+        else
+            echo "Started Syncing Storage Type from the palette Service"
+        fi
+        }
+
+        get_auth_token
+        update_scar_repo
+        update_instance_type
+        update_storage_type
+
+        echo "Wait for 5 minute for the sync process to complete."
+        EOF1
+        ```
+
+11. Grant execution permissions to the `scar-registry-update.sh` script.
+
+    ```shell
+    chmod +x scar-registry-update.sh
+    ```
+
+12. Invoke the script to update the SCAR endpoint. Replace `<cluster-url>` with the address of your {props.edition} instance and
+    `<sys-admin-password>` with the system administrator password.
+
+    ```shell
+    ./scar-registry-update.sh <cluster-url> admin <sys-admin-password>
+    ```
+
+    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 `<cluster-url>` with the
+address of your {props.edition} cluster and `<sys-admin-password>` with the system administrator password.
+
+    ```shell
+    export ENDPOINT=<cluster-url>
+    export PASSWORD=<sys-admin-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"}
+    ```