Skip to content

install.md

Latest commit

 

History

History
360 lines (257 loc) · 16.2 KB

install.md

File metadata and controls

360 lines (257 loc) · 16.2 KB
Raw

Installation

Contents

Prerequisites

Install the OpenShift GitOps operator

  1. From the Administrator's perspective, navigate to the OperatorHub page.

  2. Search for "Red Hat OpenShift GitOps". Click on the tile and then click on "Install"

  3. Keep the defaults in the wizard and click on "Install"

  4. Wait for it to show up in the list of "Installed Operators." If it doesn't install correctly, you can check its status on the "Installed Operators" page in the openshift-operators namespace.

Obtain an entitlement key

If you don't already have an entitlement key to the IBM Entitled Registry, obtain your key using the following instructions:

  1. Go to the Container software library.

  2. Click "Copy key."

  3. Copy the entitlement key to a safe place so you can use it when updating the global pull secret for the cluster.

  4. (Optional) Verify the validity of the key by logging in to the IBM Entitled Registry using a container tool:

    docker login cp.icr.io --username cp --password entitlement_key

Update the OCP global pull secret

Update the OCP global pull secret with the entitlement key.

Keep in mind that the registry user for that secret is "cp". A common mistakes is to assume the registry user is the name or email of the user owning the entitlement key.

Update the global pull secret using the OpenShift console

  1. Navigate to the "Workloads > Secrets" page in the "Administrator" perspective.

  2. Select the object "pull-secret".

  3. Click on "Actions -> Edit secret".

  4. Scroll to the bottom of that page and click on "Add credentials", using the following values for each field:

    • "Registry Server Address" cp.icr.io
    • "Username": cp
    • "Password": paste the entitlement key you copied from the Obtain an entitlement key setp
    • "Email": any email, valid or not, will work. This fields is mostly a hint to other people who may see the entry in the configuration

  5. Click on "Save"

Special note about global pull secrets on ROKS

Updating the OCP global pull secret triggers the staggered restart of each node in the cluster. However, the Red Hat OpenShift on IBM Cloud platform requires an additional step: reload all workers nodes (in the case of ROKS classic clusters) or replace all workers nodes (in the case of ROKS VPC Gen2 clusters.)

You can perform the reloading or replacement of workers directly from the cluster page in the IBM Cloud console or use a terminal, following the instructions listed here.

Update the pull secret in the openshift-gitops namespace

Global pull secrets require granting too much priviledge to the OpenShift GitOps service account, so we have started to transition to the definition of pull secrets at a namespace level.

The Application resources are transitioning to use PreSync hooks to copy the entitlement key from a Secret named ibm-entitlement-key in the openshift-gitops namespace, so issue the following command to create that secret:

 oc create secret docker-registry ibm-entitlement-key \
        --docker-server=cp.icr.io \
        --docker-username=cp \
        --docker-password="${IBM_ENTITLEMENT_KEY:?}" \
        --docker-email="non-existent-replace-with0-yours@email.com" \
        --namespace=openshift-gitops

Adding Cloud Pak GitOps Application objects to your GitOps server

The instructions in this section assume you have administrative privileges to the cluster.

After completing the list of activities listed in the previous sections, you have the option of adding the Argo CD Application objects for a Cloud Pak using either the OpenShift Container Platform console or using commands in a terminal.

Using the OCP console

  1. Launch the Argo CD console: Click on the grid-like icon in the upper-left section of the screen, where you should click on either "ArgoCD Console" (for OCP 4.6) or "Cluster Argo CD" (for OCP 4.7 and later.)

  2. The Argo CD login screen will prompt you for an admin user and password. The default user is admin . The admin password is located in a secret in the openshift-gitops namespace.

    • The secret name is either argocd-cluster-cluster (for OCP 4.6) or openshift-gitops-cluster (for OCP 4.7 and later.)

    • Switch to the openshift-gitops project, locate the secret in the "Workloads -> Secrets" selections in the left-navigation tree of the Administrator view, scroll to the bottom, and click on "Reveal Values" to retrieve the value of the admin.password field.

    • Type in the user and password listed in the previous steps, and then click the "Sign In" button.

  3. (add Argo app) Once logged to the Argo CD console, click on the "New App+" button in the upper left of the Argo CD console and fill out the form with values matching the Cloud Pak of your choice, according to the table below:

    For all other fields, use the following values:

    Field Value
    Application Name argo-app
    Path (OCP 4.6) config/argocd
    Path (OCP 4.7 and later) config/argocd-ga
    Namespace openshift-gitops
    Project default
    Sync policy Automatic
    Self Heal true
    Repository URL https://github.com/IBM/cloudpak-gitops
    Revision HEAD
    Cluster URL https://kubernetes.default.svc

  4. (add Cloud Pak Shared app) Click on the "New App+" button again and fill out the form with values matching the Cloud Pak of your choice, according to the table below:

    For all other fields, use the following values:

    Field Value
    Application Name cp-shared-app
    Path config/argocd-cloudpaks/cp-shared
    Namespace ibm-cloudpaks
    Project default
    Sync policy Automatic
    Self Heal true
    Repository URL https://github.com/IBM/cloudpak-gitops
    Revision HEAD
    Cluster URL https://kubernetes.default.svc

  5. Under "Parameters", if using OCP 4.6, replace the value of the field serviceaccount.argocd_application_controller with the value argocd-cluster-argocd-application-controller.

  6. After filling out the form details, click the "Create" button

  7. (add actual Cloud Pak) Click on the "New App+" button again and fill out the form with values matching the Cloud Pak of your choice, according to the table below:

    Cloud Pak Application Name Path Namespace
    Business Automation cp4a-app config/argocd-cloudpaks/cp4a cp4a
    Integration Automation cp4i-app config/argocd-cloudpaks/cp4i cp4i
    AIOps Automation cp4aiops-app config/argocd-cloudpaks/cp4aiops openshift-operators

    For all other fields, use the following values:

    Field Value
    Project default
    Sync policy Automatic
    Self Heal true
    Repository URL https://github.com/IBM/cloudpak-gitops
    Revision HEAD
    Cluster URL https://kubernetes.default.svc

  8. After filling out the form details, click the "Create" button

  9. Under "Parameters", if using OCP 4.6, replace the value of the field serviceaccount.argocd_application_controller with the value argocd-cluster-argocd-application-controller.

  10. Still under "Parameters", set the values for the fields storageclass.rwo and storageclass.rwx with the appropriate storage classes. For OpenShift Container Storage, the values will be ocs-storagecluster-ceph-rbd and ocs-storagecluster-cephfs, respectively.

  11. After filling out the form details, click the "Create" button

  12. Wait for the synchronization to complete.

  13. Enable auto-synchronization for the applications automatically created by the previous steps

    • For instance, if adding the "cp4a-app" application, it will automatically create two new applications, "cp4a-operators" and "cp4a-resources". The only exception is the "cp-shared-app" application, which does not bring in a "resources" application.

    • Click on the first application, such as "cp4a-operators", then select "App Details."

    • Scroll down to "Sync Policy" and select "Enable Auto-Sync."

    • Leave "Prune Resources" disabled

    • Enable "Self Heal" (this is required for some synchronizations where the first pass grants extra permissions to the Argo CD service account and the subsequent passes succeed with the extra permissions)

    • Exit the panel and wait for the synchronization to complete, then repeat the steps for the next application, which in this example would be "cp4a-resources".

Using a terminal

  1. Open a terminal and ensure you have the OpenShift CLI installed:

    oc version --client

# Client Version: 4.8.2

    Ideally, the client's minor version should not be more than one iteration behind the version of the server. Most commands here are pretty basic and will work with more significant differences, but keep that in mind if you see errors about unrecognized commands and parameters.

    If you do not have the CLI installed, follow these instructions.

  2. Log in to the OpenShift CLI

  3. Install the Argo CD CLI

  4. Log in to the Argo CD server

    Using OCP 4.6:

    # OCP 4.6
argo_route=argocd-cluster-server
argo_secret=argocd-cluster-cluster
sa_account=argocd-cluster-argocd-application-controller

argo_pwd=$(oc get secret ${argo_secret} \
            -n openshift-gitops \
            -o jsonpath='{.data.admin\.password}' | base64 -d ; echo ) \
&& argo_url=$(oc get route ${argo_route} \
               -n openshift-gitops \
               -o jsonpath='{.spec.host}') \
&& argocd login "${argo_url}" \
      --username admin \
      --password "${argo_pwd}" \
      --insecure

    Using OCP 4.7 and later (the object names change a little from OCP 4.6:)

    # OCP 4.7+
argo_route=openshift-gitops-server
argo_secret=openshift-gitops-cluster
sa_account=openshift-gitops-argocd-application-controller

argo_pwd=$(oc get secret ${argo_secret} \
            -n openshift-gitops \
            -o jsonpath='{.data.admin\.password}' | base64 -d ; echo ) \
&& argo_url=$(oc get route ${argo_route} \
               -n openshift-gitops \
               -o jsonpath='{.spec.host}') \
&& argocd login "${argo_url}" \
      --username admin \
      --password "${argo_pwd}" \
      --insecure

  5. Add the argo application. (this step assumes you still have the shell variables assigned from previous steps) :

    Using OCP 4.6:

    # OCP 4.6
argocd app create argo-app \
      --project default \
      --dest-namespace openshift-gitops \
      --dest-server https://kubernetes.default.svc \
      --repo https://github.com/IBM/cloudpak-gitops \
      --path config/argocd \
      --sync-policy automated \
      --revision main \
      --upsert

    Using OCP 4.7 and later (the object names change a little from OCP 4.6:)

    # OCP 4.7+
argocd app create argo-app \
      --project default \
      --dest-namespace openshift-gitops \
      --dest-server https://kubernetes.default.svc \
      --repo https://github.com/IBM/cloudpak-gitops \
      --path config/argocd-ga \
      --helm-set-string serviceaccount.argocd_application_controller=${sa_account} \
      --sync-policy automated \
      --revision main \
      --upsert

  6. Add the cp-shared application. (this step assumes you still have the shell variables assigned from previous steps) :

    argocd app create cp-shared-app \
      --project default \
      --dest-namespace openshift-gitops \
      --dest-server https://kubernetes.default.svc \
      --repo https://github.com/IBM/cloudpak-gitops \
      --path config/argocd-cloudpaks/cp-shared \
      --helm-set-string serviceaccount.argocd_application_controller=${sa_account} \
      --sync-policy automated \
      --revision main \
      --upsert

  7. Add the respective Cloud Pak application (this step assumes you still have shell variables assigned from previous steps) :

    # appname=<< choose a value from the "Application Name" column in the 
# table of Cloud Paks above, such as cp4a-app, cp4i-app, 
# cp4aiops-app, etc >>
cp=cp4i
app_name=${cp}-app
# app_path=<< choose the respective value from the "path Name" 
# column in the table of Cloud Paks above, such as 
# config/argocd-cloudpaks/cp4i/cp4a, config/argocd-cloudpaks/cp4i, 
# etc
app_path=config/argocd-cloudpaks/${cp}
cp_namespace=ibm-cloudpaks
gitops_branch=main

argocd app create "${app_name}" \
      --project default \
      --dest-namespace openshift-gitops \
      --dest-server https://kubernetes.default.svc \
      --helm-set-string metadata.argocd_app_namespace="${cp_namespace}" \
      --helm-set-string repoURL=https://github.com/IBM/cloudpak-gitops \
      --helm-set-string serviceaccount.argocd_application_controller=${sa_account} \
      --helm-set-string targetRevision="${gitops_branch}" \
      --path "${app_path}" \
      --repo https://github.com/IBM/cloudpak-gitops \
      --revision "${gitops_branch}" \
      --sync-policy automated \
      --upsert 
argocd app wait "${app_name}"

  8. Enable auto-synchronization for the apps automatically added by the previous step. The auto-synchronization is disabled by default in the repo if you want to further configure the applications before starting the synchronization. Note that this step assumes you still have shell variables assigned from previous steps:

    argocd app set ${cp}-operators \
         --sync-policy automated \
         --self-heal
argocd app wait ${cp}-operators \
         --timeout 1200
argocd app set ${cp}-resources \
         --sync-policy automated \
         --self-heal
argocd app wait ${cp}-resources \
         --timeout 7200

  9. List all the applications to see their overall status (this step assumes you still have shell variables assigned from previous steps):

    argocd app list -l app.kubernetes.io/instance=${app_name}