OpenShift

Clarity Transform discovers Red Hat OpenShift and Kubernetes clusters through the cluster API: nodes, namespaces, workloads, storage, routes, config maps and secret metadata. Every verb granted is get or list; nothing is written.

Where to find it

Go to Discover → Integrations, then select the OpenShift card. The card's category label is Containers. The integration's page has the Endpoints and History tabs; Integrations describes the page, its grid and its row actions.

Why we do this

In a container platform the application boundary is largely declared rather than inferred, because the platform already knows which pods constitute a service. That is a materially better starting position than a network-derived guess.

Clarity takes that declared structure as evidence, then connects it outwards to the traffic those workloads exchange with the rest of the estate, which is usually where the migration risk sits. A cluster that is self-contained is easy. A cluster whose pods call three databases on physical hardware is the problem, and that boundary is exactly what the platform itself cannot tell you.

What we collect

• Clusters and nodes, with their capacity
• Namespaces, and the workloads in them: Deployments, StatefulSets, DaemonSets, Jobs, CronJobs, Operators and Custom Resources
• Persistent volume claims and storage classes
• Routes and ingresses, which is how a workload is reached from outside the cluster
• Config maps, Helm releases and raw object manifests
• Secret metadata and a key count, never values

Secrets: metadata only, and this is the permission worth explaining up front

Clarity records a secret's namespace, name, type and a count of keys. Values are read into memory to count them and then discarded; they are never stored. This is the permission customers challenge, reasonably, and that is the honest answer to give them.

What it adds

The declared application structure. It is a statement of intent by the people who built the application, not an inference from traffic.

kube-system must be readable, for a reason that is not obvious

Its namespace identifier is what distinguishes one cluster from another. Without it, two clusters cannot be told apart, and re-running discovery against a second cluster would merge it into the first.

What is deliberately not inferred

TLS verification is disabled on the cluster API connection

Every authentication mode passes --insecure-skip-tls-verify=true, so a self-signed or internally issued API certificate connects without its CA being trusted on the Clarity host. The connection is encrypted; the server certificate is not validated. Stated here rather than left for a security review to find.

• No secret values. Metadata and a key count only, as above.
• No container images or filesystems, and no application data.
• No exec, attach or port-forward. The role grants none of them.
• Nothing is written. Every verb granted is get or list.
• Co-location in a namespace is not a dependency. A namespace is an organisational boundary; two workloads sharing one are not related by that fact alone.

What we require

The requirement below is read from rb-pautol-openshift-connect-cluster.ps1 in the Runbooks repository, which is where it is maintained. If it is wrong, the runbook is what gets corrected and this page follows on the next build.

Applies to OpenShift and to Nutanix NKP, which use the same cluster API and session model.

Account required: a dedicated ServiceAccount with a custom ClusterRole and binding. Every verb it grants is get or list only, with no write access anywhere.

Neither built-in role is sufficient, and both are commonly assumed to be:

• view grants no cluster-scoped resources, so nodes, storage classes and persistent volumes are invisible.
• cluster-reader covers those but deliberately excludes Secrets, which two discovery scripts per platform require.

Required resources: core (namespaces, nodes, services, configmaps, persistentvolumeclaims, secrets), workloads under apps (deployments, statefulsets, daemonsets), and storageclasses. A wider optional set (ingresses, networkpolicies, jobs, cronjobs, horizontalpodautoscalers, customresourcedefinitions) improves coverage where granted and is skipped cleanly where it is not.

kube-system must be readable. Its namespace identifier is what distinguishes one cluster from another, so without it clusters cannot be told apart.

Secrets: metadata only. Clarity records the namespace, the name, the type and a count of keys. Secret values are read into memory to count them, then discarded. They are never stored. This is the permission customers challenge, reasonably, and that is the honest answer to give them.

Connectivity: HTTPS to the cluster API endpoint, conventionally TCP 6443.

Do not use kubeadmin or a cluster-admin account. The custom read-only ClusterRole above is the point: an admin credential would work and would grant far more than discovery needs.

Three authentication modes are supported, not just tokens. The mode is chosen by Get-ContainerAccessMode in rb-pautol-openshift-common.ps1, in this order:

• Kubeconfig, when the endpoint's discovery method is kubeconfig (or config / kube-config), or the endpoint value is a path to an existing file, or the endpoint is blank and KUBECONFIG is set in the environment.
• Bearer token, when the discovery method is token (or bearer / bearer-token), or the credential username is literally token, bearer or oauth. The password holds the token.
• Username and password, which is the default for any ordinary username. It runs oc login into a temporary kubeconfig and removes it afterwards.

A ServiceAccount bearer token is what we ask for and what the role guidance above assumes, because it is scoped, revocable on its own and carries no interactive session. The other two modes work and are worth knowing about when a customer cannot issue a token.

Username and password needs oc specifically. kubectl has no interactive login, so where only kubectl is present on the Clarity host this mode fails with a clear error rather than falling back. Token and kubeconfig work with either CLI.

TLS verification is disabled on the cluster API connection. All three modes pass --insecure-skip-tls-verify=true, so a self-signed or internally issued API certificate connects without the CA being trusted on the Clarity host. State this rather than let a customer's security review discover it: the connection is encrypted, but the server certificate is not validated.

Verification before handover

1. Confirm the credential authenticates, in the mode you intend. Three modes are supported and the mode is inferred; it cannot be set from the Clarity UI. A username of token, bearer or oauth selects bearer-token auth with the token in the password field; any other username falls through to oc login with that username and password. Confirming which mode you got matters as much as confirming it worked.
2. Confirm the cluster-scoped resources read. This is the check that separates a working role from a plausible one. Read nodes, storage classes and persistent volumes. The built-in view role grants no cluster-scoped resources at all, so these come back empty rather than forbidden.
3. Confirm kube-system and secret metadata read. Read the kube-system namespace and list secrets in one namespace. cluster-reader covers the former and deliberately excludes the latter, which is why a custom role is needed rather than either built-in.

Configuring the endpoint

On the integration's Endpoints tab, select the add icon (Create New Integration Endpoints). The Create new entry form opens with these fields, in this order:

Field	Value
Name	A name for the endpoint
End Point	The cluster API address, conventionally on TCP 6443
Credential	Recommended: username token with the ServiceAccount bearer token as the password. An ordinary username and password also works, and uses oc login
Job Schedule	A five-field cron expression, for example 0 0 * * * (daily). Workloads change continuously in a container platform
Enabled	Ticked. The box is unticked when the form opens

The help texts: End Point "FQDN or IP Address of management system for technology e.g. vCenter, Nutanix Prism"; Credential "Credentials can be configured under Settings/Identity and Access Management/Credentials."; Job Schedule "Cron schedule – Use five fields: 〈mm〉 〈hh〉 〈day-of-month〉 〈month〉 〈weekday〉".

The Credential list offers the credentials stored under Settings → Identity & Access Management → Credentials, so create the credential there first.

No field is marked as required. Technology is set by the card and is hidden in the form. Select Save to create the endpoint, or Cancel to close the form. The edit icon opens the same fields as Edit entry.

Removing the access

Delete the ClusterRoleBinding, the ClusterRole and the ServiceAccount. Deleting the ServiceAccount invalidates its token immediately. Then, in Clarity, remove the endpoint (select its row on the Endpoints tab, then Remove selected) or clear its Enabled box, and remove the credential under Settings → Identity & Access Management → Credentials.

Troubleshooting

Symptom	Cause
Nodes, storage classes and persistent volumes are all empty	The built-in view role is bound rather than a custom one. view grants no cluster-scoped resources, so these read as empty rather than forbidden.
Everything reads except secrets	cluster-reader is bound. It covers cluster-scoped resources but deliberately excludes secrets.
Two clusters merged into one record	kube-system is not readable, so the identifier that distinguishes them was unavailable.
Authentication fails with a valid token	The credential username is not token, bearer or oauth, so the token was treated as a password and oc login was attempted with it. Rename the credential username.
Ingresses or CRDs missing	They are in the wider optional set. Discovery skips them cleanly where they are not granted, with less coverage rather than a failure.