IBM Fusion Deployment

This is an opinionated guide for running Atolio on IBM Fusion (IBM Storage Fusion), written for customers deploying Atolio alongside it. IBM Fusion runs on Red Hat OpenShift, so some steps use OpenShift tooling such as oc and OpenShift Routes. Atolio also supports other on-premises Kubernetes platforms; this guide is the recommended path when IBM Fusion is your foundation. As with every Atolio deployment, your data remains within your cluster at all times.

Unlike Atolio’s public cloud deployments, there is no Terraform step here. The cluster already exists, so you deploy Atolio directly with oc and Helm. Everything lands in a single atolio namespace.

Deployment Prerequisites

Before getting started, your Atolio support team will do the following on your behalf:

1. Provide credentials (a pull secret or registry login) for the lumen container images, along with the registry path to use in your Helm values. The vespa images are public.
2. Provide the Atolio deployment bundle, which contains:
   • The vespa, tika-pipes, and lumen Helm charts
   • Manifest templates for the namespace, platform secrets, and object storage
   • Per-chart values files
3. Coordinate identity-provider connector access for login provisioning (see Provision the first login user).

The following deployment prerequisites will help streamline your deployment process.

Determine Deployment Model

We offer both Atolio managed and customer managed deployment models for you to choose from. Please review the comparison and requirements for each approach on our Deployment Model Overview page and inform your Atolio support team which method you’d like to use for your deployment. On IBM Fusion, deployments are most commonly customer managed, with your engineers running oc and Helm with the guidance of an Atolio deployment engineer via screensharing.

Determine IBM Fusion cluster

IBM Fusion presents a Red Hat OpenShift cluster (4.12 or later) that you can reach with oc. It is available as the IBM Fusion HCI System appliance and as the software-defined IBM Storage Fusion running on an OpenShift cluster you operate; both work for Atolio. The cluster needs:

• cluster-admin access, as the vespa chart creates a SecurityContextConstraints RoleBinding.
• A default StorageClass for stateful workloads, providing block storage for the Vespa content nodes.
• An apps wildcard domain (*.apps.<cluster>.<base-domain>) served by the OpenShift router.

Both the Atolio lumen images and the public vespa images can be served from an internal registry or a local pull-through cache if you prefer to keep image pulls within your environment, as is common for disconnected IBM Fusion installations. Point the chart values at that registry.

Determine Atolio hostname

Before the deployment call, decide on the hostname for the Atolio web application, for example atolio.apps.example.com. Because Atolio is exposed through OpenShift Routes, the hostname simply needs to fall under the apps wildcard the router already serves. No separate hosted zone or DNS delegation is required, and External DNS is not used on IBM Fusion.

For the remainder of this document, we will use https://atolio.apps.example.com in the examples, but it is expected for you to replace with your own hostname.

Determine object storage

Atolio requires two S3-compatible buckets, reached over the S3 protocol. On IBM Fusion this is provided by Red Hat OpenShift Data Foundation (ODF), whose Ceph RADOS Gateway (RGW) exposes the S3 endpoint. ODF is included with the software-defined IBM Storage Fusion data services; on IBM Fusion HCI, confirm ODF is deployed, as the appliance’s default data services use IBM Storage Scale, which does not expose S3.

Use the ODF object service to create the two buckets (or ObjectBucketClaims) and an object user. You provide the endpoint, the two bucket names, the region, and an access key / secret key pair, with s3ForcePathStyle: true (Ceph RGW serves path-style).

Setup authentication

Atolio supports single sign-on (SSO) authentication through Okta, Microsoft Entra ID, Google, and Keycloak using the OpenID Connect (OIDC) protocol. Refer to Configuring Authentication for more details on the steps to complete in your desired SSO provider in order to obtain the necessary OIDC configuration values. Set the redirect URI to https://atolio.apps.example.com/* when you register the client.

Note: The OIDC issuer URL must be the external Route hostname, not an in-cluster Service URL, so that the issuer matches the tokens the browser receives. If your router presents a serving certificate your cluster does not already trust (for example the default self-signed wildcard), Atolio also needs that CA so it can fetch the OIDC discovery document and JWKS. See Application Helm value options for both settings.

Setup local environment

Finally, if an engineer from your team will be performing the deployment, ensure they have the following utilities installed:

• Install the OpenShift CLI (oc)
• Install Helm (v3.8 or later, required for OCI charts)
• Install atolioctl

Provide Deployment Engineer with Configuration

At this point if you’re proceeding with an Atolio managed deployment you’ll need to provide the information from these prerequisite steps to your Atolio deployment support team. Otherwise please ensure the information is provided to the engineer from your organization who will be performing the deployment with Atolio’s support.

To recap, provide these details:

• Atolio hostname
• Object storage endpoint, bucket names, and credentials
• OIDC Configuration
• The StorageClass name and apps wildcard domain for the cluster

If you’re opting to have Atolio manage the deployment you can disregard the remainder of this documentation as these steps will be performed by your Atolio deployment engineer. Otherwise be sure to share this documentation with the engineer from your organization that will be performing the deployment so they can familarize theirself with the steps required.

Deploy Atolio

The charts come up in order: database (vespa) and text extraction (tika-pipes) before the application services (lumen), because the lumen chart runs a Vespa bootstrap hook that communicates to vespa-admin pods to perform a database migration step.

Files that need your environment’s values or secrets ship in the bundle as *.yaml.example templates with placeholders. Copy each one, drop the .example suffix, and fill it in before applying.

Namespace and image pull secret

oc login ...                       # into your IBM Fusion cluster, as a cluster-admin
oc apply -f manifests/00-namespace.yaml
oc project atolio

# Pull secret for the lumen images (credentials provided by Atolio).
oc -n atolio create secret docker-registry atolio-pull \
  --docker-server=<ATOLIO_REGISTRY> \
  --docker-username=<USERNAME> --docker-password=<PASSWORD>

Object storage

Create the two buckets in the ODF object service and create the atolio-object-store credentials Secret with AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Record the endpoint, bucket names, and region for the lumen values below. A plain-HTTP endpoint makes the chart set disableSSL=true automatically; an https:// endpoint is used as TLS.

Platform secrets

cp manifests/lumen-secrets.yaml.example manifests/lumen-secrets.yaml
# Fill in jwtSecretKey, secretSalts, and oidcClientSecret.
oc apply -n atolio -f manifests/lumen-secrets.yaml

For the jwtSecretKey and secretSalts values any 256 bit (32 character) string can be used. These values are used to sign JWT tokens used by the web application and atolioctl tool and salt document IDs in Atolio’s database. They should be well guarded secrets that are unique to the deployment, and can be generated by running openssl rand -base64 32.

The jwtSecretKey must be at least 32 bytes. Atolio signs the session JWT with HS256 and rejects shorter keys, and that failure surfaces only at login, after authentication otherwise succeeds. The same secret is shared by the feeder, the connectors, and atolioctl.

Application Helm value options

In your copies of helm/values.lumen.yaml and helm/values.tika-pipes.yaml, replace the placeholders: the app hostname (domains.lumen), the image registry, the object-storage endpoint, buckets, and path-style flag, and the OIDC issuer and client ID. Each placeholder carries an inline comment explaining what it expects. helm/values.vespa.yaml is generic and used as-is; edit it only to change Vespa sizing or the StorageClass (set the cluster’s StorageClass here if it is not the default).

Two OIDC settings are specific to OpenShift:

oidc:
  endpoint: "https://<external issuer Route hostname>"   # never an in-cluster Service URL
  trustedCAConfigMap: "oidc-trusted-ca"                  # only if your router cert is not publicly trusted

If your router serves a certificate your cluster does not already trust, capture the ingress CA into the oidc-trusted-ca ConfigMap before installing the charts:

oc get configmap -n openshift-config-managed default-ingress-cert \
  -o jsonpath='{.data.ca-bundle\.crt}' > /tmp/router-ca.crt
oc -n atolio create configmap oidc-trusted-ca \
  --from-file=ca-bundle.crt=/tmp/router-ca.crt --dry-run=client -o yaml | oc apply -f -

If your router already serves a publicly-trusted certificate, drop the trustedCAConfigMap value.

Install the charts

helm upgrade --install vespa charts/vespa-*.tgz \
  -n atolio -f helm/values.vespa.yaml

helm upgrade --install tika-pipes charts/tika-pipes-*.tgz \
  -n atolio -f helm/values.tika-pipes.yaml

helm upgrade --install lumen charts/lumen-*.tgz \
  -n atolio -f helm/values.lumen.yaml --timeout 8m

Post-deployment steps

Deployment Verification

oc -n atolio get pods                 # all Running
oc -n atolio get pvc                  # vespa admin/content Bound
oc -n atolio get routes               # 10 lumen routes (edge)

# The vespa pods run under a scoped nonroot-v2 SCC; everything else runs under restricted-v2.
oc -n atolio get pod -l app=vespa-content \
  -o jsonpath='{.items[0].metadata.annotations.openshift\.io/scc}{"\n"}'   # -> nonroot-v2

Browse to https://atolio.apps.example.com/ and sign in through your IdP. The Route layer terminates TLS at the edge, and your apps wildcard already resolves to the router, so there is no load balancer or DNS record to wait on.

Provision the first login user

A user who authenticates at the IdP still needs to resolve to an Atolio user before they get a session. That provisioning runs an identity-provider connector, coordinated with Atolio, who supplies the connector image and the source configuration for your IdP. The connector lists your IdP’s users and publishes the records Atolio’s resolver turns into Atolio users; a user with no such record can authenticate but will not land a session. Work through this step with your Atolio contact.

When you have validated that the deployment is available, the next step is to configure sources.

Teardown

helm uninstall lumen tika-pipes vespa -n atolio
oc delete project atolio