Note:

Enable a GitHub Actions Workflow to Access a Kubernetes Cluster using OKE OpenID Connect Authentication

Introduction

In this tutorial, we authorize a GitHub Actions workflow to execute a Kubernetes command in an Oracle Cloud Infrastructure Kubernetes Engine (OCI Kubernetes Engine or OKE) cluster. By using GitHub’s native OpenID Connect (OIDC) authentication, you can avoid managing long-lived credentials and streamline secure, automated access to your OKE clusters, enabling more efficient Continuous Integration and Continuous Deployment (CI/CD) workflows.

Objectives

Task 1: Create a GitHub Repository

Create a new repository in your GitHub account. Enter your account name or organization name, and the name of your repository.

Task 2: Configure an OKE Cluster

  1. Create a Kubernetes cluster with OKE or select an existing cluster to update and note down the cluster Oracle Cloud Identifier (OCID). For more information, see Creating Kubernetes Clusters Using Console Workflows.

  2. Create a JSON file to update the cluster with the following information.

    • isOpenIdConnectAuthEnabled: Enter true.
    • issuerUrl: Enter "https://token.actions.githubusercontent.com".
    • clientId: Enter your value. In this example, we use "oke-kubernetes-cluster". This value has to match the audience in your GitHub Actions workflow.
    • requiredClaim: Enter ["repository=GH_ACCOUNT/REPO", "workflow=NAME", "ref=refs/heads/main"].
    • usernameClaim: Enter "sub".
    • usernamePrefix: Enter "actions-oidc:".

    Replace the GH_ACCOUNT, and REPO values with your values. The JSON file should look like:

    {
    "openIdConnectTokenAuthenticationConfig": {
      "isOpenIdConnectAuthEnabled": true,
      "clientId": "oke-kubernetes-cluster",
      "issuerUrl": "https://token.actions.githubusercontent.com",
      "usernameClaim": "sub",
      "usernamePrefix": "actions-oidc:",
      "requiredClaim": [
        "repository=gregvers/testoidc",
        "workflow=oke-oidc",
        "ref=refs/heads/main"
      ],
      "caCertificate": null,
      "signingAlgorithms": [
        "RS256"
      ]
    }
}

  3. Run the OCI Command Line Interface (CLI) command to update the cluster with your JSON file. Replace the CLUSTER_OCID with your values.

    oci ce cluster update --cluster-id CLUSTER_OCID --from-json file://./update.json

Task 3: Configure the Egress Network Traffic

Allow the cluster API server to egress traffic to GitHub by adding a security rule to the subnet security list of your security rules assigned to the cluster Kubernetes API endpoint.

Task 4: Configure Kubernetes Role Based Access Control (RBAC)

Configure RBAC in your Kubernetes cluster to authorize your GitHub Actions workflow to do certain operations (get/watch/list pods and get/watch/list/create/update/delete deployments) using the following YAML file. Update the following line: "name: actions-oidc:repo:GH-ACCOUNT/REPO:ref:refs/heads/main" with your GitHub account name and repository name.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: actions-oidc-role
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "watch", "list"]
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "watch", "list", "create", "update", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: actions-oidc-binding
  namespace: default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: actions-oidc-role
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: User
    name: actions-oidc:repo:GH-ACCOUNT/REPO:ref:refs/heads/main

Task 5: Configure GitHub Actions

Create an GitHub Actions workflow in your GitHub repository.

  1. Click Actions and Set up a workflow yourself.

  2. Paste the following code in the editor and update server="https://X.X.X.X:6443" with the public IP of your cluster.

    name: OKE-OIDC

on:
  # Triggers the workflow on push or pull request events but only for the "main" branch
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

permissions:
  id-token: write # Required to receive OIDC tokens

# This workflow generates a GitHub Actions OIDC token and runs kubectl command in an OKE cluster
jobs:
  oke-oidc:
    runs-on: ubuntu-latest
    steps:
      - name: Create OIDC Token
        id: create-oidc-token
        run: |
          AUDIENCE="oke-kubernetes-cluster"
          OIDC_URL_WITH_AUDIENCE="$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$AUDIENCE"
          IDTOKEN=$(curl \
            -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            -H "Accept: application/json; api-version=2.0" \
            "$OIDC_URL_WITH_AUDIENCE" | jq -r .value)
          echo "::add-mask::${IDTOKEN}"
          echo "idToken=${IDTOKEN}" >> $GITHUB_OUTPUT

      - name: Check Permissions in Kubernetes
        run: |
          kubectl \
          --token=$ \
          --server="https://X.X.X.X:6443" \
          --insecure-skip-tls-verify \
          auth can-i --list

    The Github Actions workflow will run automatically. The kubectl command will return the operations you authorized with the RBAC configuration (get/watch/list pods and get/watch/list/create/update/delete deployments).

    GitHub Action workflow execution

    Description of the illustration github-actions-workflow.png

Acknowledgments

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.