Configuring IBM Cloud Pak foundational services

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

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

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.

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.

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.

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>
              size: <volume-size>
            walStorage:
              storageClass: <your-storage-class>
              size: <volume-size>

Notes:

• If you change the storage class settings after 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 want to change the volume size settings after the foundational services installation, check if the storage class supports volume expansion. See Volume expansion.

  • If the storage class supports volume expansion, you can update the volume size settings.
  • If the storage class does not support volume expansion, contact IBM Support.

• If you are installing your IBM Cloud Pak on OpenShift Container Platform cluster with multiple zones, use the storage class with volumeBindingMode: WaitForFirstConsumer. To get the storage class with volumeBindingMode: WaitForFirstConsumer, you can, for example, by running the following command:

  oc get storageclass | grep WaitForFirstConsumer
  ibmc-vpcblock-odf-10iops                      vpc.block.csi.ibm.io   Delete          WaitForFirstConsumer   true                   2y59d
  ibmc-vpcblock-odf-5iops                       vpc.block.csi.ibm.io   Delete          WaitForFirstConsumer   true                   2y59d
  ibmc-vpcblock-odf-custom                      vpc.block.csi.ibm.io   Delete          WaitForFirstConsumer   true                   2y59d
  ibmc-vpcblock-odf-general                     vpc.block.csi.ibm.io   Delete          WaitForFirstConsumer   true                   2y59d
  ibmc-vpcblock-odf-ret-10iops                  vpc.block.csi.ibm.io   Retain          WaitForFirstConsumer   true                   2y59d
  ibmc-vpcblock-odf-ret-5iops                   vpc.block.csi.ibm.io   Retain          WaitForFirstConsumer   true                   2y59d
  ibmc-vpcblock-odf-ret-custom                  vpc.block.csi.ibm.io   Retain          WaitForFirstConsumer   true                   2y59d
  ibmc-vpcblock-odf-ret-general                 vpc.block.csi.ibm.io   Retain          WaitForFirstConsumer   true                   2y59d
  

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>

Configure the shared_buffers parameter for your EDB PostgreSQL database.

The shared_buffers parameter allocates the memory for the database server to cache data. You can adjust the value between 20% to 25% of the total spec.resources.requests.memory value. For example, if your spec.resources.requests.memory value is 600 Mi, the recommended value for the shared_buffers parameter is 150 MB.

In the following example, the spec.resources.requests.memory value is set to 600 Mi for a large profile in the common-service-db cluster instance custom resource (CR).

oc get cluster.postgresql.k8s.enterprisedb.io common-service-db -ojsonpath='{.spec.resources.requests.memory}'
600Mi

To adjust the value of the shared_buffers parameter, go to the common-service-postgresql service entry. Find the common-service-db CR, and in the spec.postgresql.parameters section, add the shared_buffers parameter. The following example shows how to set the shared_buffers parameter to 150 MB.

services:
  - name: common-service-postgresql
    spec: {}
    resources:
      - apiVersion: postgresql.k8s.enterprisedb.io/v1
        kind: Cluster
        name: common-service-db
        data:
          spec:
            postgresql:
              parameters:
                shared_buffers: 150MB

After you save the changes, restart EDB. For more information, see Restart .

Specify the number of replicas for the PostgreSQL operator. If you do not specify the number of replicas, the default number of replicas for the PostgreSQL operator is 1.

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: <your-foundational-services-namespace>
spec:
  operatorConfigs:
    - name: cloud-native-postgresql
      replicas: <number-of-replicas>

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.

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

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:

• roksEnabled: Set to false: to disable authentication with Red Hat OpenShift.
• roksURL: The public service endpoint URL of your public cloud cluster. For more information about how to get the URL, see Updating OpenShift authentication.
• roksUserPrefix: Prefix to be used with the username. When you access your cluster console or CLI, you use the prefix along with the username to authenticate with OpenShift. If you are using IM with Red Hat OpenShift Kubernetes Service in the IBM Cloud, you must set the prefix to IAM#.

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\""

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

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.>

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:

• For default authentication, use DEFAULT
• For enterprise LDAP, use LDAP
• For enterprise SAML, use SAML
• For OpenShift authentication, use ROKS
• For enterprise OpenID Connect (OIDC), use OIDC

  • The OIDC option automatically redirects with a single OIDC provider. If more than one OIDC provider is available, you need to select one at the login screen.

  • If you have multiple OIDC providers, and you need to select one at the login screen, setting the preferredLogin value as shown in the following examples is not an option.

    preferredLogin: azure_OIDC
    preferredLogin: keycloak_OIDC
    

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

Default configuration of 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>

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

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>

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

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

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:

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=""

Example configuration with default values:

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

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"