How to regenerate the admin kubeconfig file in OpenShift 4

Solution Verified - Updated

Environment

  • Red Hat OpenShift Container Platform (RHOCP) 4.x
  • oc client version 4.14.0 or later

Issue

  • Need to regenerate the kubeconfig file for the system:admin user
  • Original kubeconfig file is lost, corrupted, or has expired certificates
  • Want a simple, secure method to create a new admin kubeconfig

Resolution

OpenShift 4.14 introduced the oc config new-admin-kubeconfig command, which provides a simple and secure way to regenerate admin kubeconfig files.

Prerequisites

  • oc client: Version 4.14.0 or later installed locally
  • Cluster access: Existing authentication to the cluster with any admin credentials
  • Permissions: User with cluster-admin privileges

Note: You can use an oc 4.14+ client against OpenShift 4.0+ clusters. While Red Hat recommends matching client and cluster versions, this command uses stable APIs available in all OpenShift 4.x versions.

Procedure

Step 1: Generate New Admin Kubeconfig

Run the command with admin credentials and save the output:

oc config new-admin-kubeconfig > ~/new-admin.kubeconfig

What this does:

  • Generates a new client certificate key pair locally (private key never written to disk during generation)
  • Pushes the public certificate to the cluster for kube-apiserver to trust
  • Creates a complete kubeconfig with 10-year certificate validity
  • Outputs the kubeconfig to stdout

Step 2: Test the New Kubeconfig

export KUBECONFIG=~/new-admin.kubeconfig
oc whoami

Expected output: system:admin

Verify cluster access:

oc get nodes
oc get clusterversion

Step 3: Verify Certificate Validity

Check that the certificate has 10-year validity:

oc config view --kubeconfig=~/new-admin.kubeconfig --raw \
  -o jsonpath='{.users[*].user.client-certificate-data}' \
  | base64 -d | openssl x509 -noout -dates

Expected output should show:

  • notBefore: Current date/time
  • notAfter: Approximately 10 years from now

When cluster-admin access is lost and ssh access to the control plane is available

$ ssh core@$NODE
# mkdir -p ~/.kube
# cp /etc/kubernetes/static-pod-resources/kube-apiserver-certs/secrets/node-kubeconfigs/lb-ext.kubeconfig ~/.kube/config
# oc config new-admin-kubeconfig > ~/new-admin.kubeconfig
# rm ~/.kube/config

Troubleshooting

Command not found

Problem: bash: oc: command not found or oc config new-admin-kubeconfig: unknown command

Solutions:

  1. oc not installed or version too old:

    Check your version:

    oc version --client

    If the version is older than 4.14.0, download and install a newer version. See Getting started with the OpenShift CLI for installation instructions.

  2. Wrong oc binary in PATH: Check which oc is being used:

    which oc
/usr/local/bin/oc version --client

Error: "the server has asked for the client to provide credentials"

Problem: Not authenticated to the cluster

Solution:

oc login -u <admin-user> https://api.<cluster-name>.<domain>:6443

Then retry the oc config new-admin-kubeconfig command.

Error: "Unauthorized" or "Forbidden"

Problem: Current user lacks cluster-admin privileges

Solution:

  1. Verify your permissions:

    oc auth can-i update configmaps --namespace=openshift-config

    Should return: yes

  2. If not, authenticate as a user with cluster-admin role:

    • Use the kubeadmin user (if still exists)
    • Use another admin user
    • Use an existing admin kubeconfig

Generated kubeconfig doesn't work

Problem: Authentication fails with the new kubeconfig

Solutions:

  1. Wait a moment: The kube-apiserver may need a few seconds to reload the CA bundle

    sleep 10
oc --kubeconfig=~/new-admin.kubeconfig whoami

  2. Check certificate details:

    oc config view --kubeconfig=~/new-admin.kubeconfig --raw \
  -o jsonpath='{.users[*].user.client-certificate-data}' \
  | base64 -d | openssl x509 -noout -subject

    Expected: subject=CN = system:admin, O = system:masters

  3. Verify ConfigMap was updated:

    oc get configmap admin-kubeconfig-client-ca -n openshift-config -o yaml

Using oc 4.14+ with older OpenShift clusters

Question: Can I use oc 4.14+ client against an OpenShift 4.12 or 4.13 cluster?

Answer: Yes, this should work. The command uses standard Kubernetes ConfigMap APIs that have been stable since OpenShift 4.0.

Important notes:

  • Red Hat officially recommends matching oc client and cluster versions
  • This version skew may not be officially supported for production use
  • If you encounter issues, Red Hat support may ask you to use matching versions
  • Practical testing confirms it works with 4.12 and 4.13 clusters

Additional Information

About the admin-kubeconfig-client-ca ConfigMap

The admin-kubeconfig-client-ca ConfigMap in the openshift-config namespace contains the Certificate Authority that signs admin kubeconfig client certificates. This CA is automatically created during cluster installation.

View the CA certificate:

oc get configmap admin-kubeconfig-client-ca -n openshift-config \
  -o jsonpath='{.data.ca-bundle\.crt}' | openssl x509 -noout -dates

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.