SSRV9V_4.x - Documentation Index

Table of Contents

• Welcome
• About
  • What's new
  • Regulatory compliance
    • Considerations for FIPS
    • Services that support FIPS
    • Enabling FIPS
  • Security context constraints
  • Known issues
  • Deprecated and changed services and features
  • Release types
  • Accessibility features
  • Supported languages
  • Support
• Installer
  • Hardware requirements and recommendations for foundational services
    • Hardware requirements of starterset profile
    • Hardware requirements of small profile
    • Hardware requirements of medium profile
    • Hardware requirements of large profile
  • Supported OpenShift and Kubernetes versions
  • Supported cloud providers
  • Storage options
    • Amazon EFS storage support for foundational services
    • NFS subdir external provisioner on Amazon EFS
    • NFS support and configuration in IBM Cloud Pak foundational services
    • Provisioning with static storage configuration
  • Cluster permissions of IBM Cloud Pak foundational services
  • Installing network policies
  • Preparing to install foundational services
    • Existing instance of foundational services in the cluster
    • OpenShift Container Platform cluster
    • Configure OpenShift Container Platform cluster for services
    • Configuring an external PostgreSQL database for IM and Zen
  • Foundational services operators and versions
  • Migrating foundational services version 3.x to 4.x
    • In-place migration
    • Isolated migration
      • Preloading Mongo data
      • Configuring IM with the PostgreSQL database before installing or upgrading
    • All namespaces migration
    • Uninstalling the remaining resources after upgrading to foundational services version 4.x
  • Installing foundational services
    • Installing foundational service with Helm charts
      • Installing online
      • Installing foundational services by mirroring Cloud Pak images to a private container registry (with ibm-pak plug-in) by using Helm charts
      • Migrating to the Helm chart deployment
      • Integrating the foundational services Helm chart with Argo CD
    • Installing foundational services with OLM
      • Adding catalog sources and mirroring images
        • Mirroring images for an air-gapped cluster
          • Mirroring images with a bastion host
          • Mirroring images with a portable compute or storage device (file system)
        • Adding catalog sources to a cluster
      • Installing the operators
        • By using the OpenShift console
        • By using the CLI
        • By using a script
      • Applying your entitlement key for online installation
      • Deploying foundational services instances
        • By using the OpenShift console
        • By using the CLI
    • Upgrading foundational services with OLM
      • Adding catalog sources and mirroring images
        • Mirroring images for an air-gapped cluster
          • Mirroring images with a bastion host
          • Mirroring images with a portable compute or storage device (file system)
        • Adding catalog sources to a cluster
      • Upgrade foundational operators and services
      • Preparing IM hostname and certificate customizations before upgrading to 4.14.0 or 4.15.0
    • Uninstalling foundational services
      • Uninstalling User Data Services
  • Configuration options
    • Configuring foundational services
      • Configuration templates
      • Configuring a custom EDB operator
    • Foundational services custom resource definitions
      • CommonService-v3
      • CertManagerConfig-v1
      • CertificateRequest
      • Certificate
      • Challenge
      • ClusterIssuer
      • Issuer
      • Order
      • IBMLicensing/v1alpha1
      • IBMLicenseServiceReporter-v1alpha1
      • IBMLicensingDefinition
      • IBMLicensingMetadata
      • IBMLicensingQuerySource
    • Authorizing foundational services to perform operations on workloads in a namespace
    • Accessing the foundational services
    • Configuring high availability
    • Configuring huge pages for foundational services
    • Downloading scripts for additional configuration from specific version CASE bundle
    • Enabling Instana metric collection for foundational services
    • Enabling Turbonomic to support Vertical Pod Autoscaling for foundational services
  • Refreshing leaf certificates
  • Dependencies of foundational services
  • Cluster configuration configmap
  • Foundational services backup and restore
    • Backing up and restoring
      • For clusters with a single instance of foundational services
      • For multiple instances of foundational services
      • For coexistence of 3.x and 4.x versions
      • For Helm chart deployments
      • On OLM with Spectrum Fusion
      • For Helm chart deployments with Spectrum Fusion
      • Backing up the License Service Reporter instance
    • Rolling back and syncing
      • Common Service DB and Zen data to a specified backup
      • Common Service DB and Zen data to a specified backup with IBM Spectrum Fusion
      • Restore the MongoDB backup data to Common Service DB
    • Migrating identity management
  • Troubleshooting
    • Gather information about your foundational services installation
    • Installation issues
      • An `OperandRequest` instance has no status
      • Status of common-service-db IBM PostgreSQL cluster custom resource is stuck in the Setting up primary state or no state
      • Status of `common-service-db` PostgreSQL cluster custom resource is stuck in the `Setting up primary` state or no state
      • PostgreSQL cluster replicas get out of sync
      • EDB PostgreSQL instance is in the `Fenced` status
      • Communication issue due to too many requests error (HTTP 429) while image mirroring
      • General troubleshooting and workarounds
      • The login page fails to load
      • Operator shows Pending status in a namespace - OLM known issue
      • Uninstallation is not successful
      • IBM foundational service Operator fails to initialize resources
      • Mirroring images to the local registry fails in an air-gapped environment
      • Skopeo failure in air-gapped installation script
      • Pushing images to a single namespace in an air-gapped environment
      • Errors in CASE prerequisites or airgap.sh
      • Registry does not support multiple communication attempt during a single authentication session
      • OLM known issue: ResolutionFailed message
      • Incorrect registry configuration
      • Timeout error when retrieving CASEs
      • ImageContentSourcePolicy creation fails
      • Operator installation or upgrade fails with DeadlineExceeded error
      • Operator installation or upgrade fails with exceeded progress deadline error
      • OLM is unable to generate new install plans
      • Customization of the CommonService CR is reverted by the IBM Cloud Pak operator
      • Troubleshooting catalog issues
    • Upgrade issues
      • SAML configured with `cloudctl` isn't retained after upgrading from foundational services 3.19.x to 4.x
      • Operator upgrade fails with the pod in `CrashLoopBackOff` status- OLM known issue
      • Zookeeper pod hangs in a `CrashLoopBackOff` state
      • Operator installation hangs during upgrade
      • Upgrade process does not complete
      • Operator installation or upgrade fails with DeadlineExceeded error
      • Operator installation or upgrade fails with exceeded progress deadline error
      • `preload_data.sh` fails due to cert manager
      • `preload_data.sh` does not complete successfully
      • Upgrade of Platform UI (zen) operand fails
      • cp-console address is changed after CS operator is upgraded to v4, but IAM service is still in v3
      • Upgrade from foundational services version 3.x to version 4.x fails due to custom certificate issue
      • Administration console returns 404 after upgrading from 3.x to 4.x
      • Install strategy fails after upgrading OpenShift to 4.15.x
      • Intermittent looping occurs in large profiles
      • ConfigMap fields are reset after an upgrade
      • Invalid value error when updating the CommonService CR by using the `setup_tenant.sh` script
      • Storage size configuration in the CommonService CR isn't applied to PostgreSQL
      • EDB PostgreSQL cluster custom resource is not created during upgrade
      • Events operator fails on OpenShift Container Platform
• Business Teams Service
  • Known Issues
  • Overview
  • External database
  • Post-installation
  • Backup and Restore
  • Data Security
  • Network Flows
  • Assigning permission to manage teams
  • Managing business teams
  • Identifying teams across different environments
  • Access Control on business teams
  • APIs
    • REST API
      • REST API Examples
    • GraphQL API
      • GraphQL schema
      • GraphQL example queries
      • GraphQL example mutations
      • GraphQL API error handling
  • Audit logging for Business Teams Service
  • Business Teams Service maintenance
  • Troubleshooting
  • CRD API Reference
• Certificate management
  • Installing IBM Cert Manager
    • Installing IBM Cert Manager by using the console
    • Installing IBM Cert Manager by using the CLI
    • Installing IBM Cert Manager and Licensing by script
    • Installing IBM Cert Manager offline
    • Migrating from IBM Certificate Manager to Red Hat Cert Manager
    • Manual steps for uninstalling singleton services - cert manager
  • Installing Red Hat Cert Manager
  • Installing Red Hat Cert Manager in a disconnected environment
  • IBM Certificate Manager hardware requirements
  • Configuring IBM Cert Manager
    • Managing Cert Manager metadata
    • Configuring resources for Certificate manager
  • Foundational services cert-manager and community cert-manager version mapping
  • IBM Certificate manager (cert-manager)
    • Creating your own self-signed and CA Issuers
    • Creating Certificate manager (cert-manager) certificates
      • Customizing cert-manager certificates
      • Viewing cert-manager resources
      • Refreshing cert-manager certificates
    • Bringing your own CA Certificate
    • Bringing back your original CA Certificate
    • Enabling automatic refresh of CA signed certificates
    • Troubleshooting certificate manager service
      • Cannot access your product console on macOS
      • Problem when you install two different cert-managers
      • Cannot create Issuers or Certificates after upgrade
      • Cert Manager fails to call webhook
      • Multiple CertificateRequest objects block Certificate objects from becoming ready
      • Catalog source of the Cert Manager fails to connect in a restricted networking policy environment
      • Cert Manager memory limit is insufficient during large batch renewals
• Integrated UI
  • Supported browsers
  • Disabling auto complete on the login page
  • Enabling welcome screen before login
  • Troubleshooting Zen issues
    • Enabling additional logs for Zen pods
    • ZenService fails to be in the ready status for EDB PostgreSQL
    • Zen fails to reconcile after two cycles
    • Troubleshooting control plane installation for Zen
    • Zen operator gets stuck and restarts when you upgrade from Zen version 4.8.12 to 5.1.4
    • ZenService upgrade fails when upgrading to Zen version 6.3.0
    • ZenService installation fails with Zen 6.2.0 to 6.2.2
    • Zen operator fails when you install or upgrade to Zen version 6.0.4
    • When you create a group, its GUID is displayed in the search results instead of its displayName value
• Common Web UI
  • Accessing a cluster with the console
• Identity Management
  • IM adoption guide
    • Multiple LDAP domains
    • Authentication types
      • Delegating authentication to OpenShift
    • OIDC registration with the client custom resource
    • Auditing IM service
    • IM for your product platform users
      • Configuring single sign-on with the SAML
        • Configuring single sign-on with the SAML using your product {{site.data.keyword.gui}}
        • Configuring single sign-on with the SAML using IdP APIs
        • Configuring SAML with SCIM provisioning server
        • Configuring SAML with SCIM-compliant provider
        • Configuring SAML with JIT provisioning
        • Configuring SAML with IdP initiated login
      • Configuring single sign-on using OpenID Connect
        • Configuring OIDC with a SCIM server dependency
        • Configuring OIDC with SCIM LDAP connection
        • Configuring OIDC with LDAP dependency
        • Configuring OIDC with on-behalf-of flow for Microsoft Azure
      • Configuring LDAP connection
      • Configuring LDAP with HA failover servers
      • Custom search base support for LDAP group and user entity in SCIM group and user APIs
      • Using realmName as a query filter
      • Enabling LDAP Nested Search
      • Changing LDAP cache settings
      • Changing LDAP search settings
      • Changing SCIM LDAP search limit settings
      • Adding custom SCIM attributes
      • Updating SCIM LDAP attributes mapping
      • Enhancing SCIM group and user API performance
      • SCIM pagination support for LDAP server
      • Changing LDAP contextPool settings
      • Changing the connection pooling configuration of the EDB PostgreSQL database
      • Configuring certificate-based authentication
      • Configuring single logout (SLO) with SAML
      • Customizing Identity Management (IM) Liberty SameSite cookie settings
  • Cluster configurations
    • Allowing limited users to log in by using only LDAP
    • Updating the cp-console hostname and certificates in 4.14.0 and onward
    • Updating the cp-console hostname and TLS secret in 4.13.0 and earlier
    • Configuring LDAP SSL connections by amending server certificates into Secrets
    • Changing the cluster administrator access credentials
    • Adding a logout redirect URL
    • Configuring access and identity token validity
    • Changing the security role mappings refresh time interval that is used during authorization
    • Changing LDAP search cache variable values
    • Using a proxy server for outbound traffic
    • Configuring mutual TLS authentication between IM and LDAP server
    • Configuring the unified console
    • Removing default OpenShift routes to use your own ingress solution
    • Enabling Horizontal Pod Autoscaling
  • IM APIs
    • Preparing to run API commands
    • OIDC Registration APIs
      • Client Registration API
      • Delete the client ID
      • Call the authorization endpoint to display the login page
      • Get access token by using username and password
      • Get access token by using client_credentials
      • Get access token by using cpclient_credentials
      • Get information about a user
      • Call introspect endpoint
      • Revoke access token or refresh token
      • Get a new access token by using the refresh token
      • Get the OIDC configuration from the well-known configuration endpoint
      • Get the Liberty and iam-token keys from the JSON Web Token (JWK) endpoint
    • Identity Provider APIs
      • IdP V3 APIs
        • Registering the OIDC clients using IdP V3
          • Registering the OIDC clients
            • Registering the OIDC clients with on-behalf-of flow for Microsoft Azure
          • Deleting the registration of the client
          • Getting the list of registered OIDC clients
          • Updating the OIDC clients
          • Configuring OIDC with LDAP dependancy using IdP v3 API
          • Configuring OIDC with SCIM server dependency
        • Registering the SAML clients using IdP V3
          • SAML with SCIM dependency registration (IdP V3 registration with IBM Security Verify and Okta)
          • SAML registration without any dependency
          • SAML with LDAP dependency registration
          • Getting SAML registration by UID
          • Updating SAML registration
          • Deleting SAML registration
        • SAML metadata download by using IdP V3
        • SAML metadata export by using samlmetadata API
        • Configuring LDAP connection by using IdP V3
          • Validating LDAP configuration while creating the LDAP connection using IdP V3
          • Validating LDAP configuration while updating the LDAP connection using IdP V3
          • Registering an LDAP connection by using IdP V3
          • Getting information about all LDAP connections
          • Getting information about LDAP connection by using UID
          • Updating an LDAP connection by using IdP V3
          • Deleting an LDAP connection by using IdP V3
        • Disabling OpenShift authentication by using IdP V3 API
        • Registering certificate-based authentication with IdP V3
      • Getting the host details
      • Different schema elements for IdP V3
  • IM sample configuration
    • SCIM configuration by using your product UI
    • IBM Cloud Pak SCIM OKTA integration
    • IBM Cloud Pak SCIM Entra ID integration
    • IBM Cloud Pak JIT support for SCIM OKTA and Entra ID
    • Creating SAML and OIDC IdP groups from the console
    • Integrating SAML with Entra ID
    • Integrating IM with Keycloak
      • Integrating IM with Keycloak as SAML IDP
      • Integrating IM with Keycloak as OIDC IDP
      • Integrating IM with Keycloak as IDP with LDAP registry
    • Integrating IBM Cloud Pak with IBM Security Verify
    • Propagating attributes from IBM Cloud Paks to just-in-time (JIT) groups in a SCIM response
  • EDB PostgreSQL database backup and restore
    • Backing up EDB PostgreSQL database
    • Restoring EDB PostgreSQL database
    • Backing up and restoring the common services EDB PostgreSQL database using pg_dump
  • Configuring an external PostgreSQL database for IM
    • Setting up an external PostgreSQL database server
  • Database migration status
  • Creating Vault secrets
    • Creating Vault secrets for LDAP bind credentials
    • Creating Vault secrets for external EDB PostgreSQL credentials
  • Troubleshooting IM issues
    • Login
      • Internal server error while login Platform UI by using SAML with LDAP dependency
      • Cannot authenticate Kubeadmin user as CloudPakAdministrator by default
      • Users cannot log in to your product console
      • Cannot log in to the console by using the admin username
      • Docker login results in unencrypted password warning
      • Login too slow or times out, or invalid username or password error
      • Cannot log in to the console after reinstallation of foundational services
      • CWOAU0061E: Unable to log in to IBM Cloud Pak foundational services {{site.data.keyword.gui}}
      • Default admin cannot log in due to LDAP server issues
      • Username shows `Undefined Undefined` after login to CloudPak dashboard using SAML login option
      • Gateway timeout or blank page error while you log in to the console
      • CWWKS1406E: Unable to load the login page and an invalid client error is displayed
      • SAML login fails when you configure SAML with IdP initiated login
      • SAML authentication fails with custom endpoint certificates
      • Unable to access the CPD route when you update custom hostname
      • Database connection fails after CA certificate rotation
    • LDAP
      • Troubleshooting LDAP configuration
      • SSL handshake failure
      • Configuring LDAP over SSL
      • Troubleshooting users and user groups search issues
      • Timeout error while setting up an LDAP connection
      • Timeout error after enabling LDAP Nested search for Microsoft Active Directory
      • Client registration failure in Platform UI console
      • Intermittent login failure in Platform UI console
      • LDAP nested search for Microsoft Active Directory does not work correctly
      • SAML with LDAP dependency using V2 API does not work correctly
      • Unable to find and add the IDP users or user groups using the console
      • The display value for SCIM group members is truncated
    • Pod issues
      • platform-auth-service pod restarts multiple times
      • Pods are not scheduled
      • secret-watcher and security-onboarding pods fail to start
      • Secret watcher pod shows CrashLoopBackOff status
      • AllNamespaces upgrade from foundational services v3.23 or v3.19 to v4.11 fails to create IM operand pods
      • IM pods cannot be deployed when foundational services is configured with external EDB PostgreSQL
      • The ibm-iam-operator pod fails because of cache sync failures
    • OIDC
      • OIDC client creation is not successful
      • OIDC registration fails to update
    • API calls
      • Cannot generate IAM access token through API for external OIDC and SAML users
    • MongoDB to EDB PostgreSQL database migration
      • MongoDB to PosgreSQL database migration fails because of the data issues in MongoDB
      • IM operand pods issue during MongoDB to EDB PostgreSQL database migration
      • Zen reconciles multiple times during EDB PostgreSQL database migration
      • Mongo to EDB PostgresSL data migration is unsuccessful with error SQLSTATE 22001
    • Enabling debugging
      • Enabling debugging for user authentication issues
      • Enabling debug logging for the IM Operator
    • EDB PostgreSQL cluster is down and the pod is in `Completed` status
    • EDB instance PostgreSQL PVC is in the Pending status
    • A login issue might occur with the unified route when running a large profile
• License Service
  • Installing License Service
    • Supported platforms and hardware requirements
    • Installing License Service from public container registry
      • Installing License Service on OpenShift Container Platform
      • Installing License Service on the Kubernetes cluster
      • Installing License Service without Operator Lifecycle Manager (OLM)
    • Installing License Service from private container registry
      • Installing IBM License Service using ibm-pak plugin
      • Installing IBM License Service without Operator Lifecycle Manager (OLM)
    • Installing License Service with Argo CD
    • Installing License Service with Helm Charts
    • Installing network policies for License Service
  • License usage metering and reporting
    • Viewing and tracking license usage
    • Hyperthreading
    • Chargeback
    • Audit snapshot
    • Reported metrics
    • Retrieving license usage data
      • Per cluster from License Service
        • API authentication
          • License Service API token
          • Service account token
        • APIs
        • Obtaining a status page
    • Cluster threshold management and visualization
    • Integration with IBM Software Central
  • Configuring
    • Enabling hyperthreading feature
    • Enabling chargeback feature
    • Limiting visibility of namespaces in License Service
    • Configuring Kubernetes Ingress
    • Enabling the use of Gateway API
    • Creating routes
    • Using custom certificates
    • Cleaning existing License Service dependencies - outside of OpenShift and on OpenShift Container Platform
    • Managing License Service metadata
    • Customizing limits and requests of License Service resources
    • Enabling Instana metric collection for License Service
  • Troubleshooting License Service
    • Defining containers for licensing
      • Values of the productChargedContainers annotation
  • Uninstalling License Service
    • Uninstalling License Service from the Red Hat OpenShift Container Platform cluster
    • Uninstalling License Service from the Kubernetes cluster
    • Uninstalling License Service without Operator Lifecycle Manager (OLM)
  • Backing up and upgrading License Service
  • Tracking license usage on AWS ECS Fargate
• License Service Reporter
  • Installing and configuring License Service Reporter
    • Supported platforms
    • Hardware requirements
    • Installing License Service Reporter
      • Installing License Service Reporter from public container registry
        • Installing License Service Reporter with the OpenShift console
        • Installing License Service Reporter with the CLI
        • Installing License Service Reporter without Operator Lifecycle Manager (OLM)
      • Installing License Service Reporter from private container registry
        • Installing License Service Reporter using ibm-pak plugin
        • Installing License Service Reporter without Operator Lifecycle Manager (OLM)
      • Installing License Service Reporter with Argo CD
      • Installing network policies for License Service Reporter
    • Upgrading License Service Reporter from version 1.x (CP2.0)
    • Configuring user authentication
      • Retrieving License Service Reporter console route
      • License Service Reporter authentication with basic credentials
        • Retrieving credentials for basic authentication
        • Changing credentials
      • License Service Reporter authentication with OAuth/OIDC provider
    • Configuring Kubernetes Ingress
    • Creating routes
    • Validating License Service Reporter deployment
    • Configuring data sources
      • Configuring the License Service instance for OpenShift clusters
      • Configuring the License Service instance for non-OpenShift clusters
      • Configuring SSL certificate validation when sending data to License Service Reporter
      • Delivering license usage of software from License Metric Tool
      • Uploading License Service data from offline environments (AWS/Fargate–dedicated)
      • Verifying the License Service connection to the License Service Reporter
    • Configuring a custom certificate
    • Managing License Service Reporter metadata
    • Customizing limits and requests of License Service Reporter resources
    • Enabling Instana metric collection for License Service Reporter
  • Tracking license usage in a multicluster environment
    • Tracking license usage in multicluster environment with License Service Reporter
    • Manually tracking license usage in a multicluster environment
  • Tracking license usage on multiple clusters on AWS ECS Fargate
  • Viewing license usage on the Licensing dashboard
    • Aggregating license usage data into single pane
    • Selecting time range and filtering
    • Working with thresholds
    • Generating license usage Snapshot from all connected environments
  • Retrieving Reports with API
    • Obtaining and updating the API token
    • API calls for retrieving License Service Reporter data
  • Troubleshooting License Service Reporter
  • Uninstalling License Service Reporter
  • Backing up the License Service Reporter instance
• Usage Metering Service
  • Methodology of counting usage
  • Obtaining the audit snapshot
  • Sending data to License Service Reporter
    • Configuring the connection by using the OpenShift console
    • Configuring the connection by using the CLI
    • Configuring the scope of sending data
  • Configuring
    • Installing network policies
    • Creating routes
    • Configuring Kubernetes Ingress
    • Enabling the use of Gateway API
• Flink
  • Overview
  • Troubleshooting Flink issues
    • Adding debug console properties for operand pods to retrieve debug logs
    • Adding debug console properties for operator pods to retrieve debug logs
    • Checking and adding SSL debug logs for certificate issues in the operand pod
    • Checking and adding SSL debug logs for certificate issues in the operator pod
    • Flink operand pods fail to run
    • TLS-proxy (nginx) container fails to start
    • Pods fail after an OpenShift cluster is restarted
    • FlinkDeployment CR status is DEPLOYED_NOT_READY
• Opensearch
  • Overview
  • Configuring OpenSearch custom resources
  • Troubleshooting OpenSearch issues
    • New pods cannot join the cluster during or after upgrade from Elasticsearch to OpenSearch
• Support
  • Open source support
  • Opening a support case
  • Collecting support information with MustGather
• Notices