Nubus for Kubernetes - Operation Manual 1.x

Deployment of Intercom Service

9. Deployment of Intercom Service#

The Intercom Service is an intermediary for communication between applications like Nextcloud, OX App Suite, and Matrix. It’s part of the Nubus for Kubernetes architecture, but not part of the default deployment.

This section describes the deployment of the Intercom Service in a Kubernetes cluster for Nubus. It covers the mandatory configuration settings and the deployment commands.

See also

Intercom Service

in Univention Nubus for Kubernetes - Architecture Manual [2] for information about purpose and architecture of the Intercom Service.

univention_ics Repository at OpenCoDE

for the repository of the Helm Chart.

9.1. Mandatory settings for Intercom Service#

Intercom Service needs various settings for the Helm Chart for its deployment. The Helm Chart key-value pairs listed are mandatory. You need to define them in your custom_values_ics.yaml values file before you can deploy Intercom Service. You also need to ensure that you use a separate values file than for Nubus.

Listing 9.1 shows an example that you can copy as basis for your adjustments. It’s recommended that you deactivate all services in Intercom Service and only activate the ones, you really use. Intercom Service has enabled all services by default.

For a reference list about the Helm Chart values for Intercom Service, see Helm Chart reference for Intercom Service.

Listing 9.1 Example custom_values_ics.yaml values file#
ics:
  default:
    domain: "ics.example.com"
  secrets: "some_secret_for_ics"
  oidc:
    secret: "some_secret_for_ics_OIDC_client"
  portal:
    apiKey:
      name: "nubus-portal-server-central-navigation-shared-secret"
      key: "authenticator.secret"
    url: "portal.example.com"
  redis:
    password: "some_password_for_redis"
  ingress:
    host: "ics.example.com"
  provisioning:
    config:
      nubusBaseUrl: "ics.example.com"
      keycloak:
        username: "kcadmin"
        credentialSecret:
          name: "nubus-keycloak-credentials"
          key: "admin_password"
      ics_client:
        credentialSecret:
          name: ""
          key: ""
  keycloak:
    enabled: true
    realm: "nubus"
    subdomain: "id.example.com"
  matrix:
    enabled: false
  nordeck:
    enabled: false
  portal:
    enabled: false
  openxchange:
    enabled: false
  nextcloud:
    enabled: false

9.2. Encrypted connection to key-value database#

Intercom Service uses the Redis key-value database to silently manage authenticated sessions in the background. For example, you can use Intercom Service with an encrypted connection to Redis in clusters that don’t allow unencrypted connections. This section describes how to configure an encrypted connection to Redis through the Helm Chart, and how to optionally also configure a custom CA.

To configure an encrypted connection to Redis, follow these steps:

  1. To enable SSL, add the respective lines in Listing 9.2 in your custom_values_ics.yaml values file.

    Listing 9.2 Enable encrypted connection to the Redis database#
    ics:
  redis:
    host: "<your-redis-connection-host>"
    port: "<your-redis-connection-port>"
    password: "<your-redis-connection-password>"
    ssl:
      enabled: true

  2. Optional: To use a custom CA when validating the server’s TLS certificate, add the lines from Listing 9.3 to your custom_values_ics.yaml values file.

    Listing 9.3 Add custom CA for the encrypted connection to Redis#
    ics:
  redis:
    ssl:
      enabled: true
      customca: |
        -----BEGIN CERTIFICATE-----
        <your-custom-CA>
        -----END CERTIFICATE-----

  3. Optional: To provide a client certificate for mTLS authentication, add the lines from Listing 9.4 to your custom_values_ics.yaml values file.

    Listing 9.4 Activate mTLS and add certificate#
    ics:
  redis:
    ssl:
      mTLS:
        enabled: true
        clientCert: |
          -----BEGIN CERTIFICATE-----
          <client-certificate>
          -----END CERTIFICATE-----
        clientKey: |
          -----BEGIN PRIVATE KEY-----
          <client-certificate-key>
          -----END PRIVATE KEY-----

    If you have a Kubernetes secret containing the mTLS certificate and its key, you can use that one instead. See Listing 9.5.

    Listing 9.5 Activate mTLS and use existing TLS secret#
    ics:
  redis:
    ssl:
      mTLS:
        enabled: true
        existingSecret:
          name: "<your-tls-secret-name>"

    See also

    TLS Secret in Secrets | Kubernetes

    for more information about the Kubernetes TLS secret object.

  4. To apply the configuration, follow the steps in Deploy Intercom Service.

9.3. Helm Chart reference for Intercom Service#

This section provides a reference for the Helm Chart values available for Intercom Service.

ics.default.domain#

Defines the base domain for the subdomains of the apps.

ics.secrets#

Defines the value of the shared secret with other services. Intercom Service also uses this setting to sign the session cookie.

It needs to have the same value as provisioning.config.ics_client.clientSecret.

ics.issuerBaseUrl#

Defines the base URL of the issuer. You either define ics.keycloak.url and ics.keycloak.realm or issuerBaseUrl.

ics.keycloak.url#

Defines the URL to Keycloak as FQDN. It’s mutual exclusive with ics.keycloak.subdomain.

Example:

https://id.example.com

ics.keycloak.realm#

Defines the Keycloak realm for Intercom Service.

ics.keycloak.subdomain#

Defines the subdomain where Intercom Service can reach Keycloak. Set the value to combined values of global.subDomains.keycloak and global.domain.

Example:

id.example.com.

ics.oidc.secret#

Intercom Service registers itself as OIDC client to Keycloak. This setting defines the secret for the Intercom Service OIDC client.

ics.portal.apiKey#

Defines the API key to the Nubus Portal Service. Provide a mapping with the following content:

  • name: <release-name>-portal-server-central-navigation-shared-secret

  • key: authenticator.secret

ics.portal.url#

Defines the URL of the Nubus Portal Service. Set the value to the combined values of global.subDomains.portal and global.domain

Example:

portal.example.com

ics.redis.host#

Defines the FQDN for the Redis database that Intercom Service connects to.

ics.redis.port#

Defines the TCP port for the Redis database connection. According to Install Redis the default port number is 6379.

ics.redis.password#

Defines the password for the Redis cache service. You need to define the password in the values file.

ics.redis.ssl.enabled#

Controls if Intercom Service uses an encrypted connection to the Redis database. The default value is false.

When you set the value to true, also read Encrypted connection to key-value database for information about the setup around an encrypted connection.

ics.redis.ssl.customca#

Holds a custom CA certificate for the connection to the Redis database so that Intercom Service can validate the TLS certificate.

ics.redis.ssl.mTLS.enabled#

Controls if Intercom Service uses mTLS for the encrypted connection to the Redis database. The default value is false.

When you set the value to true, also read Encrypted connection to key-value database for information about the setup around an encrypted connection.

ics.redis.ssl.mTLS.clientCert#

Holds the client certificate for the mTLS configuration for the connection to the Redis database.

ics.redis.ssl.mTLS.clientKey#

Holds the client key for the mTLS configuration for the connection to the Redis database.

ics.redis.ssl.mTLS.existingSecret.name#

Defines the secret name to an existing Secret object that contains the mTLS certificate and the mTLS key. For the required keys in the secret, see TLS Secret in Secrets | Kubernetes.

ics.ingress.host#

Defines the FQDN for Intercom Service. The user’s browser must resolve it, because the browser is the client that uses Intercom Service functionality.

Example:

ics.example.com

Mostly, the client to the services is the user’s browser and not the services in the cluster network themselves.

provisioning.config.nubusBaseUrl#

Set it to the same value as ics.ingress.host in URL format.

Example:

https://ics.example.com

provisioning.config.keycloak.username#

The username to a user account in Keycloak that has permission to create a client in Keycloak. Intercom Service uses this user account to create the client in Keycloak on its own.

provisioning.config.keycloak.credentialSecret#

In Nubus the secret <release-name>-keycloak-credentials contains the value in the key admin_password. You can either set the value here or provide a pointer to the secret in the secret map. Provide a map with name and key, as shown in the example in Listing 9.1.

provisioning.config.keycloak.password#

Define the value for the provisioning.config.keycloak.username in this setting or use provisioning.config.keycloak.credentialSecret.

Recommendation:

Use provisioning.config.keycloak.credentialSecret.

provisioning.config.ics_client.credentialSecret#

Defines where to find the secret for the Intercom Service client. Provide a map with name and key, as shown in the example in Listing 9.1.

It needs to have the same value as ics.secrets and provisioning.config.ics_client.clientSecret.

provisioning.config.ics_client.clientSecret#

Define the value for the Intercom Service client secret.

It needs to have the same value as ics.secrets.

Recommendation:

Use provisioning.config.ics_client.credentialSecret.

9.4. Deploy Intercom Service#

To deploy Intercom Service, use the following steps:

  1. Make sure you configured the mandatory settings in your custom_values_ics.yaml values file for Intercom Service.

  2. Define the environment variables for the Helm chart command, as shown in Listing 9.6. For the current version, see the changelog of the Intercom Service.

    Listing 9.6 Define environment variables for Intercom Service deployment#
    $ export RELEASE_NAME="nubus-ics"
$ export VERSION="<the-ics-version>"

  3. Deploy Intercom Service with Helm using the command in Listing 9.7.

    Listing 9.7 Deploy Intercom Service through Helm#
    $ helm upgrade \
   --install \
   --values custom_values_ics.yaml \
   --version "$VERSION" \
   "$RELEASE_NAME" \
   oci://artifacts.software-univention.de/nubus/charts/intercom-service
On this page