Configuring IBM Cloud Pak foundational services

The IBM Cloud Pak foundational services operator creates the CommonService custom resource (CR) in the foundational-services namespace.

The custom resource has the services, cluster configurations, and hardware profile that you can set before or after you install foundational services.

You can access the CommonService custom resource by using the OpenShift Container Platform console or by using the command-line interface (CLI).

oc edit CommonService common-service -n <your-foundational-services-namespace>

Parameters in the CommonService CR

The CommonService CR has some parameters that control the placement of the OperandRegistry and OperandConfig in various deployment topologies. For more information about the topologies, see Topologies that need the IBM NamespaceScope Operator.

Updating the custom resource

Set the following parameters by adding them to the CommonService custom resource. You can update these parameters before you create an OperandRequest instance or after you install the services. Add or modify the parameters and values in the spec section.

Approval strategy

The approval strategy defines whether the approval is needed to install, or upgrade IBM Cloud Pak foundational services. By default, the approval strategy is set to Automatic, however, you can change this setting during installation. You can also set the approval strategy after the installation by adding or changing the installPlanApproval parameter in the custom resource. If the approval strategy is set to Automatic, the operator is automatically installed or upgraded when a new version is available. If you set the installPlanApproval parameter to Manual, the operator is not automatically installed or upgraded. Instead, you get an an install plan that needs to be manually approved before an upgrade.

Notes:

Changing approval strategy from Automatic to Manual

To change the approval strategy from Automatic to Manual, change the installPlanApproval parameter value to Manual in the spec section of the CommonService CR.

Note: If the installPlanApproval parameter is not in the CR, add the following line to the CR in the spec section: installPlanApproval: Manual.

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  installPlanApproval: Manual

Changing approval strategy from Manual to Automatic

Note: Before you begin, make sure that the operators that are not a part of IBM Cloud Pak foundational services in the namespace have the installPlanApproval parameter set to Automatic in the subscription. Otherwise, even if you change the approval strategy from Manual to Automatic for the IBM Cloud Pak foundational services operator, this setting might be overwritten.

To change the approval strategy from Manual to Automatic, complete the following steps:

  1. Change the installPlanApproval parameter value to Automatic in the spec section of the CommonService CR.

Note: If the installPlanApproval parameter is not in the CR, add the following line to the CR in the spec section: installPlanApproval: Automatic.

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  installPlanApproval: Automatic

Bring your own CA Certificate

You can replace the foundational services self-signed certificate authority (CA) certificate with your own CA certificate in either of the following ways:

Note: Anytime you need to bring back your original certificate, see Bringing back your original CA Certificate.

If you are updating the CommonService CR to bring your own certificate, first update BYOCACertificate: true in the spec section of the CommonService CR.

Note: If BYOCACertificate specification is not in the CR, you can add it in the spec section as shown in the following example:

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  BYOCACertificate: true

After you update the CommonService CR, complete the following steps to replace the foundational services self-signed CA certificate with your own CA certificate:

  1. Prepare and have your Transport Layer Security (TLS) certificate, TLS private key, and CA certificate ready.

  2. Create a backup of the foundational services self-signed CA certificate. By default, the certificate is created in the foundational-services namespace.

     oc get certificate cs-ca-certificate -n <your-foundational-services-namespace> -o yaml > cs-ca-certificate.yaml

  3. Delete the foundational services self-signed CA certificate resource so that the cert-manager service does not re-create the updated secret.

     oc delete certificate cs-ca-certificate -n <your-foundational-services-namespace>

  4. Delete the foundational services self-signed CA certificate secret.

     oc delete secret cs-ca-certificate-secret -n <your-foundational-services-namespace>

  5. Re-create the cs-ca-certificate-secret secret with your CA certificate (ca.crt), TLS certificate (tls.crt), and private key (tls.key).

     oc -n <your-foundational-services-namespace> create secret generic cs-ca-certificate-secret --from-file=ca.crt=<your path>/ca.crt  --from-file=tls.crt=<your path>/tls.crt  --from-file=tls.key=<your path>/tls.key

  6. Refresh the leaf certificates that are created by individual foundational services. For more information and steps to refresh the leaf certificates, see Refreshing cert-manager certificates.

License

Note: To enable IBM Support, you must accept the license. For more information about Licensing acceptance, see License Accept.

Accept the licenses to use the services. To do so, add spec.license.accept: true in the spec section of the CRs. See the following samples:

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  license:
    accept: true
  size: as-is

apiVersion: operator.ibm.com/v1alpha1
kind: IBMLicensing
metadata:
  name: instance
spec:
  license:
    accept: true

apiVersion: operator.ibm.com/v1
kind: CertManagerConfig
metadata:
  name: default
spec:
  license:
    accept: true

apiVersion: operator.ibm.com/v1
kind: NamespaceScope
metadata:
  name: common-service
  namespace: <foundational-services-namespace>
spec:
  license:
    accept: true

Hardware profile

Set the hardware requirements profile based on the workloads in your cluster. For more information about the profiles, see Hardware requirements and recommendations for foundational services.

You can use the templates to update the hardware requirements of the services that you are installing. You can also use the templates to set the configuration parameters of the services.

The default profile is starterset (starter). You can change the profile to small, medium, or large (production), if required. If you are upgrading your cluster from a previous release, the default profile setting is as-is, which means that the hardware requirements setting from the previous release is retained.

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  size: as-is

Storage class

Instead of specifying the storage class for each service in the spec.<service-name> section, you can specify a storage class for all services in the spec section. Any service that needs to use a storage class will then use this specified storage class.

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  size: as-is
  storageClass: <storage-class-name>

When you specify a storage class in the spec section, the storage class of a service is updated to reflect this value only if the service is not yet deployed.

Services configuration

Add any service-related configuration in the spec.services section. First, add services: under spec:. You need to add services: section only once. You can add all services-related configuration under the same section.

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  services:

Then, add the service configuration. For example, if you are adding a storage class for MongoDB, the configuration would be as shown in the following example:

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  services:
  - name: ibm-im-mongodb-operator
    spec:
      mongoDB:
        storageClass: cephfs

Add Labels to foundational services resources

Add labels to all foundational services resources including IM, IM MongoDB, and IDP Config UI

Specify the labels that you want to add to all foundational services resources in the spec section of the CommonService CR. The labels are added to all the resources that are created by the foundational services.

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  labels:
    cpfssupport/addOnId: service-name
    some-other-label-key: some-other-label-value

Add labels to specific foundational services resources including IM, IM MongoDB, and IDP Config UI

Specify the labels that you want to add to specific foundational services resources in the spec.services section of the CommonService CR. The labels are added to the specific resources that are created by the foundational services.

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  services:
  - name: ibm-im-operator
    spec:
      authentication:
        labels:
          cpfssupport/app: im
          some-other-label-key: some-other-label-value
  - name: ibm-idp-config-ui-operator
    spec:
      commonWebUI:
        labels:
          cpfssupport/app: idp-config-ui
          some-other-label-key: some-other-label-value
  - name: ibm-im-mongodb-operator
    spec:
      mongoDB:
        labels:
          cpfssupport/app: im-mongodb
          some-other-label-key: some-other-label-value

Add labels to Certificate manager service

Specify the labels that you want to add to the Certificate manager service resources in the spec section of the CertManagerConfig CR. The labels are added to all the resources that are created by the Certificate manager service. See Managing Certificate Manager metadata for more information.

Add labels to License service

Specify the labels that you want to add to the License service resources in the spec section of the IBMLicensing CR. The labels are added to all the resources that are created by the License service. See Managing License Service metadata for more information.

Add labels to License service reporter

Specify the labels that you want to add to the License service reporter resources in the spec section of the IBMLicenseServiceReporter CR. The labels are added to all the resources that are created by the License service reporter. See Managing License Service Reporter metadata for more information.

Federal Information Processing Standard (FIPS)

For information on configuring foundational services to enable FIPS, see Enabling FIPS.

Ephemeral storage setting

Huge pages settings

foundational services supports allocation and consumption of pre-allocated huge pages for a service. To enable huge pages for foundational services, you must configure the huge pages setting in Red Hat® OpenShift® Container Platform first. For more information, about configuring huge pages on Red Hat OpenShift Container Platform, see What huge pages do and how they are consumed by applications.

Huge pages settings are supported for Identity Management (IM) and its dependency Cloud Native Postgresql only. You can enable huge pages setting by specifying huge pages allocation in the spec section.

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: huge-pages-common-service
spec:
  size: small
  hugepages:           
     enable: true
     hugepages-<size>: <allocation>

Cloud Native Postgresql settings

Storage class (common-service-postgresql)

Specify a storage class name for the persistent volume. If you do not add the storage class configuration, the default storage class that is available in the cluster is used for PostgreSQL Cluster CR.

services:
  - name: common-service-postgresql
    spec: {}
    resources:
      - apiVersion: postgresql.k8s.enterprisedb.io/v1
        kind: Cluster
        name: common-service-db
        data:
          spec:
            storage:
              storageClass: <your-storage-class>
            walStorage:
              storageClass: <your-storage-class>

Note: If you change the storage class settings after the foundational services installation, the changes are not applied to the existing PostgreSQL cluster. The changes are applied only to the new PostgreSQL clusters that are created after the storage class settings are updated.

If you are installing your IBM Cloud Pak on IBM Cloud®, use the ibmc-file-gold-gid or ibmc-block-gold storage class.

Configuring resources for PostgreSQL cluster (common-service-postgresql)

Specify resource settings. If you do not specify a setting, the default resource settings that are available in the cluster are used for PostgreSQL cluster.

services:
  - name: common-service-postgresql
    spec: {}
    resources:
      - apiVersion: postgresql.k8s.enterprisedb.io/v1
        kind: Cluster
        name: common-service-db
        data:
          spec:
            instances: 3 
            resources:
              limits: 
                cpu: <cpu-limit>
                memory: <memory-limit>
                ephemeralStorage: <ephemeral-storage-limit>
                hugepages-<size>: <allocation>  # enabled only if hugepages is enabled for the cluster
              requests: 
                cpu: <cpu-request>
                memory: <memory-request>
                ephemeralStorage: <ephemeral-storage-request>

MongoDB settings

Storage class (ibm-im-mongodb-operator)

Specify a storage class name for the persistent volume. If you do not add the storage class configuration, the default storage class that is available in the cluster is used for MongoDB.

- name: ibm-im-mongodb-operator
  spec:
    mongoDB:
      storageClass: <storage_class_name>

Note: If you change the resource settings post upgrade, the default settings get restored.

If you are installing your IBM Cloud Pak on IBM Cloud®, use the ibmc-file-gold-gid or ibmc-block-gold storage class.

Changing the default values of the MongoDB username and password (ibm-im-mongodb-operator)

The ibm-im-mongodb-operator generates default username and password, which are random strings. You can change these parameter values before you install the IBM Cloud Pak foundational services.

  1. Get the base64-encoded values of the new username and password.
echo <new-username or new-password> | base64

  1. Define a YAML file of kind Secret. Use the foundational-services namespace, and the base64-encoded username and password values in this YAML file. Following is a sample file:

     apiVersion: v1
 kind: Secret
 metadata:
   name: icp-mongodb-admin
   namespace: <your-foundational-services-namespace>
 type: Opaque
 data:
   password: SFV6a2NYMkdKa2tBZA==
   user: dGpOcDR5Unc=

  2. Create the secret by running the following command:

     kubectl apply -f <YAML-file-name>.yaml

Configuring resources for MongoDB (ibm-im-mongodb-operator)

Specify resource settings. If you do not specify a setting, the default resource settings that are available in the cluster are used for MongoDB.

replicas:
  resources:
    requests:
      cpu: <cpu-request>
      memory: <memory-request>
      ephemeral-storage: <ephemeral-storage-request>
    limits:
      cpu: <cpu-limit>
      memory: <memory-limit>
      ephemeral-storage: <ephemeral-storage-limit>

Authentication settings

Changing the default cpadmin username

The IBM Cloud Pak foundational services installation creates a default cpadmin user, who is a cluster administrator. You can customize the username by adding the defaultAdminUser parameter.

Note: If you already have a user by the name cpadmin in your cluster, you must set the defaultAdminUser parameter with a custom name that is not admin before you install foundational services. This is to avoid your admin user from being removed if you uninstall foundational services later.

- name: ibm-im-operator
  spec:
    authentication:
      config:
        defaultAdminUser: <custom-username>

Delegating authentication to OpenShift (ibm-im-operator)

Authentication with Red Hat OpenShift is enabled by default. The ibm-im-operator has the following default configuration. If you do not update these parameters, authentication with OpenShift is enabled with no prefix.

- name: ibm-im-operator
  spec:
    authentication:
      config:
        roksEnabled: true
        roksURL: <your-endpoint-URL>
        roksUserPrefix: ""

You can disable the authentication, or update the parameters as required. Following are the parameter descriptions:

Assigning the cloud pak administrator privileges to an OpenShift user

If you are delegating authentication to OpenShift, you can assign the cloud pak administrator privileges to an existing OpenShift user. The user can be added to the bootstrapUserId parameter.

To add the bootstrapUserId parameter before IM service installation, see the following configuration:

- name: ibm-im-operator
  spec:
    authentication:
      config:
        bootstrapUserId: "<custom-username>"

To add the bootstrapUserId parameter after IM service installation, see Changing the default cluster administrator.

Adding custom OIDC claims

The IM service uses the default scopes and claims that WebSphere® Application Server Liberty provides. Based on your OIDC authentication requirements, you can customize the OIDC claims that are returned by the UserInfo endpoint.

To add the custom claims before you install the IM service, add the following configuration:

- name: ibm-im-operator
  spec:
    authentication:
      config:
        claimsSupported: "<list-of-claims>"
        claimsMap: "<list-of-claims-map>"
        scopeClaim: "profile=<list-of-claims-in-the-profile>"

See the following example:

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  size: medium
  services:
  - name: ibm-im-operator
    spec:
      authentication:
        config:
          claimsSupported: "name,family_name,display_name,given_name,preferred_username"
          claimsMap: "name=\"givenName\" family_name=\"givenName\" given_name=\"givenName\" preferred_username=\"givenName\" display_name=\"displayName\""
          scopeClaim: "profile=\"name,family_name,display_name,given_name,preferred_username\""

Disabling nonce

To improve security, nonce is enabled by default. Nonce associates a client session with an ID token and is used in authentication to ensure that attackers do not use old sessions.

To disable nonce, add the following configuration:

- name: ibm-im-operator
  spec:
    authentication:
      config:
        nonceEnabled: false

Adding description of the login options (ibm-idp-config-ui-operator)

You can configure multiple authentication types in your cluster. For more information, see Authentication types.

The authentication types that you configure in your cluster are displayed on the console login page. You can provide a short description of the authentication types in the ibm-idp-config-ui-operator by configuring these parameters. The description is then displayed on the console login page.

- name: ibm-idp-config-ui-operator
  spec:
    globalUIConfig:
      enterpriseLDAP: <Provide a short description about the enterprise LDAP authentication type.>
      defaultAuth: <Provide a short description about the default authentication type.>
      osAuth: <Provide a short description about the OpenShift authentication type.>
      enterpriseSAML: <Provide a short description about the enterprise SAML authentication type.>

Setting the preferred login options (ibm-im-operator)

If you configured multiple authentication types in your cluster, but you want the console login page to display any one or a selected set of the configured login options, you can set the preferredLogin: parameter. For example, preferredLogin:SAML,LDAP.

Use the following parameter values:

- name: ibm-im-operator
  spec:
    authentication:
      config:
        preferredLogin: <option1>,<option2>,<optionN>

Changing the OIDC issuer URL (ibm-im-operator)

Default configuration of OpenID Connect (OIDC) in your product uses <cluster_address>:443 in the authentication endpoints, which are used to authenticate users to Kubernetes. However, in the oidcIssuerURL, local host IP address is used, the default value of which is https://127.0.0.1:443/idauth/oidc/endpoint/OP. If required, you can change the oidcIssuerURL endpoint to use a hostname for Kubernetes authentication. If you want to use the .well-known/openid-configuration endpoint, you must update the oidcIssuerURL with the hostname that you want to use.

- name: ibm-im-operator
  spec:
    authentication:
      config:
        oidcIssuerURL: <https://<hostname>:443/oidc/endpoint/OP>

Changing the provider issuer URL (ibm-im-operator)

If you want to use the .well-known/openid-configuration endpoint, you must update the providerIssuerURL with the hostname that you want to use. You can use the endpoint to get the OIDC configuration information of the provider. The default setting is providerIssuerURL: ''.

- name: ibm-im-operator
  spec:
    authentication:
      config:
        providerIssuerURL: <https://<hostname>:443/idprovider/v1/auth/.well-known/openid-configuration

Changing the cluster name (ibm-im-operator)

The default cluster name is mycluster. You can change the cluster name by using the clusterName parameter. The cluster name is used in Cloud Resource Names (CRNs).

- name: ibm-im-operator
  spec:
    authentication:
      config:
        clusterName: <custom-name>

HA configuration

If you are configuring high availability (HA) in your cluster, add the following configuration for the IM operator:

- name: ibm-im-operator
   spec:
     authentication:
       replicas: 3

Sample ibm-im-operator operator section in the custom resource

Following is a sample configuration of the ibm-im-operator operator in the custom resource. The sample includes the authentication with Red Hat OpenShift and OIDC URL parameters.

- name: ibm-im-operator
    spec:
      authentication:
        config:
          bootStrapUserId: clusteradmin
          roksEnabled: true
          roksURL: 'https://c100-e.eu-de.containers.cloud.ibm.com:32301'
          roksUserPrefix: 'IAM#'
          oidcIssuerURL: 'https://c100-e.eu-de.containers.cloud.ibm.com:443/oidc/endpoint/OP'
          preferredLogin: ROKS

Configuring resources for IM (ibm-im-operator)

Specify resource settings. If you do not specify a setting, the default resource settings that are available in the cluster are used for IM.

  - name: ibm-im-operator
    spec:
      authentication:
        replicas: 1
        authService:
          resources:
            limits:
              cpu:
              memory:
              ephemeral-storage:
              hugepages-<size>:    # enabled only if hugepages is enabled for the cluster
            requests:
              cpu:
              memory:
              ephemeral-storage:
        clientRegistration:
          resources:
            limits:
              cpu:
              memory:
              ephemeral-storage:
              hugepages-<size>:   # enabled only if hugepages is enabled for the cluster
            requests:
              cpu:
              memory:
              ephemeral-storage:
        identityManager:
          resources:
            limits:
              cpu:
              memory:
              ephemeral-storage:
              hugepages-<size>:   # enabled only if hugepages is enabled for the cluster
            requests:
              cpu:
              memory:
              ephemeral-storage:
        identityProvider:
          resources:
            limits:
              cpu:
              memory:
              ephemeral-storage:
              hugepages-<size>:  # enabled only if hugepages is enabled for the cluster
            requests:
              cpu:
              memory:
              ephemeral-storage:

License Service settings

License Service configuration is available in the IBMLicensing CR. see more information in the Configuring and verifying completeness of License Service.

MustGather settings

MustGather configuration settings

Table 1. MustGather configuration settings
Parameter Description Default value Syntax
gatherConfig Set the MustGather configuration parameters such as data modules, namespaces and labels. "" String

Example configuration with default values:

apiVersion: operator.ibm.com/v1alpha1
kind: MustGatherConfig
metadata:
  name: default
spec:
  gatherConfig: |-
    modules="overview,system,failure,ocp,cloudpak"
    namespaces="common-service,ibm-common-services"
    labels=""

MustGather job settings

Table 2. MustGather job settings
Parameter Description Default value Syntax
serviceAccountName Set the name of the service account for the MustGather job. default String
mustgatherConfigName Set the name of the MustGather config. default String

Example configuration with default values:

apiVersion: operator.ibm.com/v1alpha1
kind: MustGatherJob
metadata:
  name: example-mustgatherjob
spec:
  serviceAccountName: default
  mustgatherConfigName: default

MustGather service settings

Table 3. MustGather service settings
Parameter Description Default value Syntax
persistentVolumeClaim.name Set the name of the MustGatherService Persistent Volume Claim. default String
persistentVolumeClaim.storageClassName Set the name of the storage class that will be used to dynamically create a PV. The storage permissions use the OpenShift default UID, GID and supplemental-groups.
Note: If you install an IBM Cloud Pak on IBM Cloud, use the ibmc-file-gold-gid storage class.		 Cluster chooses one storage class in the list. String
mustgather.name Set the name of the MustGather service deployment. default String
mustgather.serviceAccountName Set the service account name for the MustGather service deployment. default String
mustgather. nodeSelector Set the node selector for the MustGather service deployment. none String
mustgather. tolerations Set the MustGather service deployment tolerations. none String
mustgather. securityContext Set the MustGather service deployment securityContext. none String
mustgather. replicas Set the MustGather service deployment replicas. 0 int32

The MustGather support information is used for troubleshooting purposes, and no backup or restore is needed.

Example configuration with default values:

apiVersion: operator.ibm.com/v1alpha1
kind: MustGatherService
metadata:
  name: must-gather-service
spec:
  # Add fields here
  persistentVolumeClaim:
    name: must-gather-pvc
    storageClassName: ""
    resources:
      requests:
        storage: 5Gi
  mustGather:
    name: must-gather-service
    replicas: 1
    serviceAccountName: default
    nodeSelector:
      node-role.kubernetes.io/worker: ""
    tolerations:
    - effect: NoSchedule
      key: dedicated
      operator: Exists
    - key: CriticalAddonsOnly
      operator: Exists
    securityContext:
      allowPrivilegeEscalation: false
      capabilities:
        drop:
        - ALL
      readOnlyRootFilesystem: true
      runAsNonRoot: true
    resources:
      requests:
        memory: "64Mi"
        cpu: "50m"
      limits:
        memory: "512Mi"
        cpu: "500m"

Certificate management service settings

Cert Manager configuration is available in the CertManagerConfig CR. See more information in the Configuring IBM Cert Manager.

Common Web UI settings

Table 8. Settings for Common Web UI
Parameter Description Default value Syntax
commonWebUI.resources.limits.cpu Sets the CPU limit for commonWebUI container. 300m Kubernetes CPU units (String)
commonWebUI.resources.limits.memory Sets the memory limit for commonWebUI container. 256Mi Bytes (String)
commonWebUI.resources.requests.cpu Sets the CPU request for commonWebUI container. 300m Kubernetes CPU units (String)
commonWebUI.resources.requests.memory Sets the memory request for commonWebUI container. 256Mi Bytes (String)
replicas (use instead of replicaCount) Sets the number of commonWebUI replicas. 1 Integer

Example configuration with default values:

- name: ibm-idp-config-ui-operator
    spec:
      commonWebUI:
        replicas: 1
        resources:
          requests:
            memory: 256Mi
            cpu: 300m
            ephemeral-storage: 251Mi
          limits:
            memory: 256Mi
            cpu: 300m

Specify resource settings. If you do not specify a setting, the default resource settings that are available in the cluster are used for the common UI service.

- name: ibm-idp-config-ui-operator
  spec:
    commonWebUI:
      replicas: 1
      resources:
        requests:
          memory:
          cpu:
          ephemeral-storage:
        limits:
          memory:
          cpu:
          ephemeral-storage: