Installing the IBM App Connect Operator by using a Helm chart in an air-gapped or online environment

Before you begin

• Ensure that you have administrator authority or have been granted the appropriate role-based access control (RBAC) to administer the cluster.
• Ensure that you are logged in to your Kubernetes environment.
• If you want to install into an air-gapped cluster, you must have mirrored the App Connect images to a private registry in your cluster.

About this task

The values file (/ibm-appconnect/values.yaml) in the directory that you downloaded earlier contains the default configuration settings for deploying the IBM App Connect Operator. When you install the Operator, you can override the values in this file in either of these ways:

• Before you run the helm install command to install the Helm chart, update the values.yaml file with your preferred values.
• When you run the helm install command, apply individual overrides at the command line.

For more information, see Configuration properties in the values.yaml file for deploying the IBM App Connect Operator.

cd /tmp/appconn-12.21.0-helm

Procedure

To install the IBM App Connect Operator by using a Helm chart, complete the following steps:

1. If you need to, set up a namespace for the IBM App Connect Operator and the Helm chart that are deployed when you run the helm install command:

   kubectl create namespace namespaceNameOperator

   Skip this step if you have an existing namespace that you want to use instead.

   Restriction: Do not install into any of the initial or system namespaces, which might impose restrictions on assigning role-based access control (RBAC) permissions or security context constraints:

   • The default namespace
   • Any namespace prefixed with kube-

2. Run the following command to select the new namespace that you created in the previous step, or to select an existing namespace that you want to use:

   kubectl config set-context --current --namespace=namespaceNameOperator

3. Create an image pull secret in the namespace where you want to deploy the Operator. This secret is needed to authenticate to the registry where the images are stored, and to enable the Operator images to be pulled from the registry. Complete the relevant step for your environment and registry:
   • Air-gapped or online environment that pulls from a private registry: Run the following command to create a pull secret for authenticating to the private registry where you mirrored the images, or to a private registry where you saved the images:

     kubectl create secret docker-registry my-registry-key --docker-server=private-registry-server --docker-username=myUsername --docker-password=myPassword --docker-email=myEmail

   • Online environment that pulls from the IBM Entitled Registry: To create a pull secret for authenticating to the IBM Entitled Registry, complete the following steps.
     Note: You can skip this step and instead create a pull secret after the Operator is installed, as described in Obtaining and applying your IBM Entitled Registry entitlement key. (The Operator installation itself doesn't require a pull secret, but you will need a secret to pull software images for the App Connect components after the Operator is installed.)
     1. Obtain an entitlement key that is needed to pull App Connect images from the IBM Entitled Registry:
        1. Log in to the IBM Container software library with the IBMid and password that are associated with the entitled software.
        2. To obtain a new key, click Get entitlement key or Add new key, and then click Copy.

           If you have an existing key to use, click Copy.

        3. Save the entitlement key for use later.
     2. Run the following command to create a pull secret for authenticating to the IBM Entitled Registry. Name the secret ibm-entitlement-key, use cp as the username, your entitlement key as the password, and cp.icr.io as the Docker server:

        kubectl create secret docker-registry ibm-entitlement-key --docker-server="cp.icr.io" --docker-username=cp --docker-password="myEntitlementKey"

4. To run the helm install command to install the Helm chart, complete the following steps:
   
   1. Online environment only: Complete either of these steps to specify configuration values for deployment and to install the chart:
      • Update the values.yaml file and then run the helm install command:
        1. Open the file in a text editor and update the values that you want to override. For more information, see Configuration properties in the values.yaml file for deploying the IBM App Connect Operator.
        2. Save your changes and then close the file.
        3. To install the Operator, run the following command:

           helm install \
              releaseName chartName \
              -n helmChartInstallationNamespace

           Where:

           • releaseName is the release name that identifies the Operator.
           • chartName is the Helm chart name.
           • helmChartInstallationNamespace is the namespace where you want to install the Helm chart.

           This sample command uses the default release name and chart name to install the IBM App Connect Operator in the namespace (for example, ace-operator) that is specified in the values.yaml file. The command also installs the Helm chart in the same ace-operator namespace in the cluster.

           helm install ibm-appconnect ./ibm-appconnect-operator -n ace-operator

      • Apply individual overrides to the default values in the values.yaml file by using the --set flag when you run the helm install command:

        helm install \
           releaseName chartName \
           -n helmChartInstallationNamespace \
           --set property1=value1 \
        ... 
           --set propertyN=valueN

        Where:

        • releaseName is the release name that identifies the Operator.
        • chartName is the Helm chart name.
        • helmChartInstallationNamespace is the namespace where you want to install the Helm chart. Set this value to the namespace to which the Operator is deployed.
        • property represents a configuration property in Configuration properties in the values.yaml file for deploying the IBM App Connect Operator and value is your preferred value. Review the listed properties to determine which default configuration values you want to override, or which unspecified values you want to set.
        This sample command uses the default release name and chart name to install the Helm chart in a namespace named ace-operator. The command also specifies the following overrides:

        • An override to install the IBM App Connect Operator in the same ace-operator namespace as the chart.
        • An override to allow the Operator to manage App Connect instances in all namespaces.

        helm install \
           ibm-appconnect ./ibm-appconnect-operator \
           -n ace-operator \
           --set namespace="ace-operator" \
           --set operator.installMode="AllNamespaces"

      The output for the helm install command should indicate that the Operator was deployed as shown in the following example:

      NAME: ibm-appconnect
      LAST DEPLOYED: Thu May 30 13:39:53 2024
      NAMESPACE: ace-operator
      STATUS: deployed
      REVISION: 1
      TEST SUITE: None
      NOTES:
      The AppConnect Operator has been deployed!
      
      To verify your install, look for:
      - Operator pod:                     kubectl get pod | grep 'ibm-appconnect-ibm-appconnect-operator'
      - MutatingWebhookConfigurations:    kubectl get mutatingwebhookconfigurations | grep 'ace-operator'
      - ValidatingWebhookConfigurations:  kubectl get validatingwebhookconfigurations | grep 'ace-operator'
      - Cluster Role:                     kubectl get clusterrole | grep 'ibm-appconnect-ace-operator-ibm-appconnect-operator'
      - Cluster Role Binding:             kubectl get clusterrolebinding | grep 'ibm-appconnect-ace-operator-ibm-appconnect-operator'
      - Role:                             kubectl get role | grep 'ibm-appconnect-ace-operator-ibm-appconnect-operator'
      - Role Binding:                     kubectl get rolebinding | grep 'ibm-appconnect-ace-operator-ibm-appconnect-operator'
      - Service Account:                  kubectl get serviceaccount | grep 'ibm-appconnect'

   2. Air-gapped environment only: Complete either of these steps to specify configuration values for deployment and to install the chart:
      • Update the values.yaml file and then run the helm install command:
        1. Open the file in a text editor and update the values that you want to override. For more information, see Configuration properties in the values.yaml file for deploying the IBM App Connect Operator.
        2. Save your changes and then close the file.
        3. To install the Operator, run the following command:

           helm install \
              releaseName chartName \
              -n helmChartInstallationNamespace

           Where:

           • releaseName is the release name that identifies the Operator.
           • chartName is the Helm chart name.
           • helmChartInstallationNamespace is the namespace where you want to install the Helm chart.

           This sample command uses the default release name and chart name to install the IBM App Connect Operator in the namespace (for example, ace-operator) that is specified in the values.yaml file. The command also installs the Helm chart in the same ace-operator namespace in the cluster.

           helm install ibm-appconnect ./ibm-appconnect-operator -n ace-operator

      • Apply individual overrides to the default values in the values.yaml file by using the --set flag when you run the helm install command:

        helm install \
           releaseName chartName \
           -n helmChartInstallationNamespace \
           --set property1=value1 \
        ... 
           --set propertyN=valueN

        Where:

        • releaseName is the release name that identifies the Operator.
        • chartName is the Helm chart name.
        • helmChartInstallationNamespace is the namespace where you want to install the Helm chart. Set this value to the namespace to which the Operator is deployed.
        • property represents a configuration property in Configuration properties in the values.yaml file for deploying the IBM App Connect Operator and value is your preferred value. Review the listed properties to determine which default configuration values you want to override, or which unspecified values you want to set.
        This sample command uses the default release name and chart name to install the Helm chart in a namespace named ace-operator. The command also specifies the following overrides:

        • An override to install the IBM App Connect Operator in the same ace-operator namespace as the chart.
        • An override to specify where to find the image for the Operator deployment.
        • An override to specify the private registry that contains the images that the Operator needs and the pull secret for authenticating to this registry.

        helm install \
           ibm-appconnect ./ibm-appconnect-operator \
           -n ace-operator \
           --set namespace="ace-operator" \
           --set operator.deployment.repository="my.private.registry.example.com/appconnect-airgap-docker-local/k8s" \
           --set operator.privateRegistry="my.private.registry.example.com/appconnect-airgap-docker-local/k8s" \
           --set operator.imagePullSecrets=["my-secret-name"]

      The output for the helm install command should indicate that the Operator was deployed as shown in the following example:

      NAME: ibm-appconnect
      LAST DEPLOYED: Thu May 30 13:39:53 2024
      NAMESPACE: ace-operator
      STATUS: deployed
      REVISION: 1
      TEST SUITE: None
      NOTES:
      The AppConnect Operator has been deployed!
      
      To verify your install, look for:
      - Operator pod:                     kubectl get pod | grep 'ibm-appconnect-ibm-appconnect-operator'
      - MutatingWebhookConfigurations:    kubectl get mutatingwebhookconfigurations | grep 'ace-operator'
      - ValidatingWebhookConfigurations:  kubectl get validatingwebhookconfigurations | grep 'ace-operator'
      - Cluster Role:                     kubectl get clusterrole | grep 'ibm-appconnect-ace-operator-ibm-appconnect-operator'
      - Cluster Role Binding:             kubectl get clusterrolebinding | grep 'ibm-appconnect-ace-operator-ibm-appconnect-operator'
      - Role:                             kubectl get role | grep 'ibm-appconnect-ace-operator-ibm-appconnect-operator'
      - Role Binding:                     kubectl get rolebinding | grep 'ibm-appconnect-ace-operator-ibm-appconnect-operator'
      - Service Account:                  kubectl get serviceaccount | grep 'ibm-appconnect'

5. Run the following commands to verify the status of the Operator deployment:

   helm ls

   You should see output that is similar to this:

   
   NAME                 NAMESPACE          REVISION      UPDATED                                   STATUS        CHART                               APP VERSION
   ibm-appconnect       ace-operator       1             2024-06-03 14:12:30.225442 +0100 BST      deployed      ibm-appconnect-operator-12.21.0     12.21.0

   kubectl get pods

   You should see output that is similar to this:

   NAME                              READY   STATUS    RESTARTS   AGE
   ibm-appconnect-5ff87d696b-bgvxg   1/1     Running   0          2m31s