All Products
Search

This Product

    Container Service for Kubernetes:Use the kubeconfig recycle bin to manage kubeconfig files

    Document Center

    Container Service for Kubernetes:Use the kubeconfig recycle bin to manage kubeconfig files

    Last Updated:Mar 26, 2026

    Container Service for Kubernetes (ACK) issues kubeconfig files to Alibaba Cloud accounts, Resource Access Management (RAM) users, and RAM roles. These files contain identity credentials for accessing ACK clusters. If a kubeconfig file is accidentally deleted or you need to recover an older version, restore it from the recycle bin within 30 days of deletion.

    Prerequisites

    Before you begin, ensure that you have:

    Use cases

    • Recover from accidental deletion: Admin A accidentally deleted the kubeconfig file that RAM User B uses to access Cluster 1. RAM User B can ask Admin A to restore the file from the recycle bin.

    • Restore a previous version with specific RBAC permissions: Admin A deleted kubeconfig v1, which had specific role-based access control (RBAC) permissions. RAM User B obtained a new kubeconfig v2, but some applications still depend on v1's RBAC permissions. To restore v1, Admin A must first delete v2, then find and restore v1 from the recycle bin.

    Restore kubeconfig files

    The recycle bin holds kubeconfig files deleted within the past 30 days. Files older than 30 days are permanently removed and cannot be recovered.

    1. Log on to the ACK console. In the left-side navigation pane, click Authorizations.

    2. Click the KubeConfig File Management tab, then click KubeConfig File Recycle Bin in the upper-right corner. The recycle bin lists all kubeconfig records deleted within the past 30 days. The following table describes the columns.

      Column Description
      Username and UID The name and ID of the Alibaba Cloud account, RAM user, or RAM role associated with the kubeconfig file
      Certificate CN The CommonName of the client certificate. See Client certificate CommonNames
      Cluster Name and Cluster ID The ACK cluster that the kubeconfig file was issued for
      RBAC Permissions The RBAC permissions granted by the kubeconfig file
      Recycled At When the kubeconfig file was deleted and moved to the recycle bin
      Deletion Interval When the record will be permanently deleted. After 30 days, the record is removed and cannot be restored

    3. Click Restore in the Actions column for the kubeconfig file you want to recover. This restores both the kubeconfig file and its associated RBAC permissions. To recover multiple files at once, select them and click Batch Restore. When batch restoring, make sure the selected files do not conflict with each other.

      If the Restore button is dimmed, an active kubeconfig file already exists for this Alibaba Cloud account, RAM user, or RAM role on this cluster. Each Alibaba Cloud account, RAM user, or RAM role can use only one kubeconfig file to access an ACK cluster. Delete the active kubeconfig file first, then restore the historical version. For more information, see Delete kubeconfig files.

    Delete kubeconfig records

    If you no longer need a kubeconfig file, delete its record from the recycle bin. Deleted records cannot be restored.

    1. Log on to the ACK console. In the left-side navigation pane, click Authorizations.

    2. Click the KubeConfig File Management tab, then click KubeConfig File Recycle Bin in the upper-right corner.

    3. Find the record you want to delete, click Delete, and enter the client certificate CommonName to confirm.

    Client certificate CommonNames

    A client certificate CommonName identifies the client that uses the kubeconfig file to access an ACK cluster. For more information, see kube-apiserver.

    In ACK, CommonNames follow the {UserID}-{SuffixID} format:

    • UserID: The ID of the RAM user or RAM role

    • SuffixID: A random string that changes each time the kubeconfig file is revoked or deleted, preventing older versions from being reused to access the cluster

    FAQ

    Why does a RAM user have multiple kubeconfig records for the same cluster in the recycle bin?

    Each time a kubeconfig file is revoked or deleted, the CommonName suffix changes and a new record is created. This is expected behavior — multiple records reflect the history of kubeconfig files issued to that identity.

    How do I identify the right record to restore?

    Check the RBAC Permissions column to find the record that matches the permissions you need. If that is not sufficient, run the following command against your existing kubeconfig file to get its CommonName, then match it against the Certificate CN column in the recycle bin.

    openssl x509 -in <(kubectl config view --kubeconfig {Kubeconfig file name} --raw --minify --output=jsonpath='{.users[0].user.client-certificate-data}'|base64 -d) -noout -subject

    What causes kubeconfig restoration to fail?

    • Insufficient RBAC permissions: Restoring a kubeconfig file also restores its RBAC permissions. If you do not have the same RBAC permissions on the ACK cluster, the restoration may fail. Grant the required RBAC permissions first. For more information, see Grant RBAC permissions to RAM users or RAM roles.

    • Abnormal cluster status: If the ACK cluster is in an abnormal state and inaccessible, the restoration fails.

    • Kubeconfig conflict: Another kubeconfig file is already active for the same identity on the same cluster. When this happens during batch restore, ACK automatically restores the most recent record and skips the conflicting ones.

    What's next

    • Delete kubeconfig files issued to former employees or files that may pose security risks. For more information, see Delete kubeconfig files.

    • If an active kubeconfig file is exposed or compromised, revoke it and issue a new one. For more information, see Revoke a KubeConfig file.