oc-login
is a GitHub Action to log into an OpenShift cluster, and preserve that Kubernetes context for the remainder of the job.
See the OpenShift Documentation for an explanation of a log in using oc
, which this action wraps.
Getting Started with the Action (or, see example)
-
oc
must be installed on the GitHub Action runner you specify.- The Ubuntu Environments come with
oc
installed. - If you want a different version of
oc
, or if you are using the Mac or Windows environments, use theopenshift-tools-installer
action to installoc
before running this action.- See the multiplatform example
- The Ubuntu Environments come with
-
Find your OpenShift Server URL.
- If you have already performed an
oc login
locally, runoc whoami --show-server
. - Otherwise, in the Web Console, click your profile name, then Copy Login Commmand. The
--server
option contains the OpenShift server URL. - At this time, the cluster must be available on the internet, so the Action runner can access it.
- If you have already performed an
-
Decide how you are going to log into the OpenShift server from the action.
- The recommended approach is to create a functional Service Account and use its token.
- The primary advantage of Service Accounts is that by default, their tokens do not expire.
- You can also use a personal token.
- If you have already logged in locally, use
oc whoami --show-token
. - Otherwise, you can retrieve your token from the Web Console, using the same steps as in Step 2.
- Personal tokens generally expire after 12 or 24 hours, depending on how your cluster is configured.
- If you have already logged in locally, use
- You can also use your personal credentials (username and password).
- If both token and credentials are provided, the credentials take precedence and the token is ignored.
- The recommended approach is to create a functional Service Account and use its token.
-
Determine how you are going to manage SSL/TLS certificate verification. If your cluster uses self-signed certificates (which is the default), the GitHub runner will not recognize the certificate and will not allow you to issue HTTPS requests.
- The easiest way to get around this is to set the
insecure_skip_tls_verify
input totrue
. - You can also obtain the self-signed certificate data (from a
.crt
file) and use thecertificate_authority_data
input.
- The easiest way to get around this is to set the
-
Store the Server URL and any credentials (passwords, tokens, or certificates) in GitHub Secrets.
- Refer to the GitHub documentation.
- You can name them anything you like. See below for an example.
-
Create your workflow.
- Refer to
action.yml
for the full list of inputs. - See the example workflow.
- See the multiplatform workflow for an example which installs
oc
andkubectl
into the runner first.
steps:
- name: Authenticate and set context
uses: redhat-actions/oc-login@v1
env:
# These can be stored in secrets, if desired.
OPENSHIFT_USER: my-username
OPENSHIFT_NAMESPACE: my-namespace
with:
# URL to your OpenShift cluster.
# Refer to Step 2.
openshift_server_url: ${{ secrets.OPENSHIFT_SERVER }}
# Authentication Token. Can use username and password instead.
# Refer to Step 3.
openshift_token: ${{ secrets.OPENSHIFT_TOKEN }}
# Credentials, if desired instead of token.
# Username and password override token if they are set.
openshift_username: ${{ env.OPENSHIFT_USER }}
openshift_password: ${{ secrets.OPENSHIFT_PASSWORD }}
# Disables SSL cert checking. Use this if you don't have the certificate authority data.
insecure_skip_tls_verify: true
# This method is more secure, if the certificate from Step 4 is available.
certificate_authority_data: ${{ secrets.CA_DATA }}
# Optional - this sets your Kubernetes context's current namespace after logging in.
namespace: ${{ env.OPENSHIFT_NAMESPACE }}
By default, the cluster name is masked, since it can be used to derive the server URL. Set reveal_cluster_name
to true
to skip masking the cluster name if you wish it to be visible in the workflow logs.
If the oc-login
step succeeds:
- The Kubernetes config generated by
oc
will be saved into a file - The
KUBECONFIG
environment variable will be set to that file - The rest of the job will have access to the Kubernetes context, so you can run any
oc
orkubectl
commands you like.
Note that if you start another job
, the new job will use a new container, and you will have to run this action again.
Since the kubeconfig contains secrets, it should not be uploaded in an artifact, and cannot set as an output from this action.
See the multiplatform workflow. All 3 runner operating systems are supported.
See the note in Step 1 regarding installing oc
into the non-Ubuntu runners.
Anyone can contribute to this project.
This project uses a pre-commit hook to ensure consistency between the source code and distribution, as well as between the source code and action.yml
. This is verified by the CI Checks
workflow.
After cloning this repository, install the hooks by running:
cd oc-login/
cp -r scripts/git-hooks/ .git/hooks/
Then run npm ci
to install dependencies, and you should be ready to develop.
See CHANGELOG.md.