cluster-reader role, and is read-only by design: agents can describe the cluster and cannot change it.
Prerequisites
- An HTTPS path from CloudThinker to the cluster’s API server, usually on port
6443. On CloudThinker Cloud, allow CloudThinker’s egress IPs: these docs don’t publish the list, so ask your CloudThinker contact, or contact us. See Reaching private services. On a self-hosted deployment, allow your CloudThinker deployment. - The
occommand-line tool, signed in to the cluster as a user who can create service accounts and bind cluster roles, such as a cluster administrator. - The Admin role in your CloudThinker workspace, which can add and edit connections. See Roles.
Setup
Create a service account
Grant read access
cluster-reader cluster role, which can view most objects in the cluster but can’t modify them:Create a token
- Token with an expiry
- Long-lived token
2160h asks for 90 days, but the cluster can return a token with a shorter or longer lifetime. When the token expires, the connection stops working: create a new one and enter it in the connection.Get the API server address and CA certificate
oc is signed in to:oc configuration:Add the connection in CloudThinker
Red Hat OpenShift connected; the cluster runs <version>. and the connection shows Connected.Connection details
Required permissions
The token sees exactly what its service account can read. Pick one:<project>:
The service account cannot read the cluster version., grant that one read:
Agent capabilities
oc or the OpenShift web console.
Verify the connection
Example prompts
payments with one of your projects.
Troubleshooting
Except for the last one, the accordion titles below are the exact messages CloudThinker shows when the connection test fails.The API server's certificate is not trusted. Add the cluster CA certificate to the connection.
The API server's certificate is not trusted. Add the cluster CA certificate to the connection.
The cluster CA certificate is not a valid PEM certificate.
The cluster CA certificate is not a valid PEM certificate.
-----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. If you copied certificate-authority-data, decode it with base64 --decode first.OpenShift rejected the token. Create a new service account token.
OpenShift rejected the token. Create a new service account token.
The service account cannot read the cluster version. Bind it to the cluster-reader cluster role.
The service account cannot read the cluster version. Bind it to the cluster-reader cluster role.
cluster-reader, or for project access grant the cluster version read in Required permissions, then connect again.Could not reach the API server. Check the URL and port.
Could not reach the API server. Check the URL and port.
6443), and that the network path in Prerequisites is open.Enter the API server URL, for example https://api.prod.example.com:6443.
Enter the API server URL, for example https://api.prod.example.com:6443.
https:// address and port, with no path. The web console address is not the API server: print the right one with the oc config view command in Setup.That address answered, but not as an OpenShift API server.
That address answered, but not as an OpenShift API server.
That API server has no OpenShift cluster version. Is it OpenShift?, which also appears for a plain Kubernetes cluster: use the Kubernetes connection for those. If the message starts OpenShift answered and mentions a redirect code, enter the address the API server answers on directly.An agent says it can't read nodes or cluster operators
An agent says it can't read nodes or cluster operators
cluster-reader to read nodes and cluster operators, or ask about a project the service account can read.Security
- Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
- Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
- Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
- Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.
- Use a dedicated read-only service account with an expiring token. You can revoke it without affecting other tools, and a leaked token stops working on its own.
- Token stays on your API server. CloudThinker sends the token only to the API server URL you enter, always verifies the server’s certificate, and never follows a redirect.