{"id":28741024,"url":"https://github.com/aliyuncontainerservice/ack-ram-authenticator","last_synced_at":"2025-06-16T07:09:54.921Z","repository":{"id":57495009,"uuid":"182072747","full_name":"AliyunContainerService/ack-ram-authenticator","owner":"AliyunContainerService","description":"Using Alibaba Cloud credentials to authenticate to a Kubernetes cluster","archived":false,"fork":false,"pushed_at":"2024-09-13T06:54:19.000Z","size":9011,"stargazers_count":31,"open_issues_count":1,"forks_count":9,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-30T12:34:36.924Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AliyunContainerService.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-18T11:09:34.000Z","updated_at":"2024-09-13T06:54:24.000Z","dependencies_parsed_at":"2024-06-19T00:23:57.336Z","dependency_job_id":"7869046e-dec2-4fca-a2ed-afadc0aad9a9","html_url":"https://github.com/AliyunContainerService/ack-ram-authenticator","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/AliyunContainerService/ack-ram-authenticator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliyunContainerService%2Fack-ram-authenticator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliyunContainerService%2Fack-ram-authenticator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliyunContainerService%2Fack-ram-authenticator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliyunContainerService%2Fack-ram-authenticator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AliyunContainerService","download_url":"https://codeload.github.com/AliyunContainerService/ack-ram-authenticator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliyunContainerService%2Fack-ram-authenticator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260116644,"owners_count":22961065,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-16T07:09:53.747Z","updated_at":"2025-06-16T07:09:54.904Z","avatar_url":"https://github.com/AliyunContainerService.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ACK RAM Authenticator for Kubernetes\n\nA tool to use AlibabaCloud RAM credentials to authenticate to a Kubernetes cluster.\n\n## Why do I want this?\nIf you are an administrator running a Kubernetes cluster on AlibabaCloud, you already need to manage AlibabaCloud RAM credentials to provision and update the cluster.\nBy using AlibabaCloud RAM Authenticator for Kubernetes, you avoid having to manage a separate credential for Kubernetes access.\n\nIf you are building a Kubernetes installer on AlibabaCloud, AlibabaCloud RAM Authenticator for Kubernetes can simplify your bootstrap process.\nYou won't need to somehow smuggle your initial admin credential securely out of your newly installed cluster.\nInstead, you can create a dedicated `KubernetesAdmin` role at cluster provisioning time and set up Authenticator to allow cluster administrator logins.\n\n## How do I use it?\nAssuming you have a cluster running in AlibabaCloud and you want to add AlibabaCloud RAM Authenticator for Kubernetes support, you need to:\n 1. Create an RAM role or user you'll use to identify users.\n 2. Create an CRD in your cluster to store the mapping between RAM roles and Kubernetes users.\n 3. Configure the mapping relationship between RAM identities and RBAC permissions.\n 4. Run the Authenticator server as a DaemonSet.\n 5. Configure your API server to talk to Authenticator.\n 6. Set up kubectl to use Authenticator tokens.\n\n### 1. Create an RAM role\nFirst, you must create one or more RAM roles that will be mapped to users/groups inside your Kubernetes cluster.\nThe easiest way to do this is to log into the RAM Console:\n - Choose the \"RAM Roles\" / \"Create RAM Role\" option.\n - Select type of trusted entity \"Alibaba Cloud Account\", Select Trusted Alibaba Cloud Account \"Current Alibaba Cloud Account\".\n - Type in a name at \"RAM Role Name\" and click \"OK\"\n\nThis will create an RAM role with no permissions that can be assumed by authorized users/roles in your account.\nNote the AlibabaCloud Resource Name (ARN) of your role, which you will need below.\n\nYou can also skip this step and use:\n - An existing role (such as a cross-account access role).\n - An RAM user (see `mapUsers` below).\n\n### 2. Create an CRD\nThe Authenticator server uses a custom resource definition (CRD) to store the mapping between RAM roles and Kubernetes users.\n\nYou can create this CRD with `kubectl apply -f ramidentitymapping.yaml`, ramidentitymapping.yaml see [`ramidentitymapping.yaml`](deploy/ramidentitymapping.yaml).\n\n### 3. Configure the mapping relationship between RAM identities and RBAC permissions\nYou need to configure the mapping relationship between RAM identities and RBAC permissions.\nFirst you need to create a RAM identity mapping with `kubectl apply -f example-ramidentitymapping.yaml`, example-ramidentitymapping.yaml see [`example-ramidentitymapping.yaml`](deploy/example-ramidentitymapping.yaml).\nThen you need to configure the mapping relationship between RAM identities and RBAC permissions with `kubectl apply -f example-binding.yaml`, example-binding.yaml see [`example-binding.yaml`](deploy/example-binding.yaml).\n\u003e [NOTE]\n\u003e Please modify example-binding.yaml and example-ramidentitymapping.yaml by prompted to use.\n### 4. Run the server\nThe server is meant to run on each of your master nodes as a DaemonSet with host networking so it can expose a localhost port.\n\nFor a sample ConfigMap and DaemonSet configuration, see [`example.yaml`](deploy/example.yaml).\nYou can run the server with `kubectl apply -f example.yaml`.\n\nThe example.yaml file including the content of `init container`, the `init container` to generate a certificate, key, and kubeconfig files by ack-ram-authenticator binary file, and mount these files to the host.\n\n\u003eNOTE\n\u003ePlease replace `\u003cyour-cluster-id\u003e` with actual cluster id in the example.yaml files.\n#### (Optional) Pre-generate a certificate, key, and kubeconfig\nIf you're building an automated installer, you can also pre-generate the certificate, key, and webhook kubeconfig files easily using `ack-ram-authenticator init --cluster-id=\u003cyour-cluster-id\u003e`,and delete init container content form example.yaml file.\n\nYou nedd run the following command to place the generated files in the desired path.\n`mkdir -p /var/ack-ram-authenticator /etc/kubernetes/ack-ram-authenticator \u0026\u0026mv cert.pem key.pem /var/ack-ram-authenticator \u0026\u0026mv ack-ram-authenticator.kubeconfig /etc/kubernetes/ack-ram-authenticator/kubeconfig.yaml`\n\nYou need run the following command to give the generated files the correct permissions.\n`chown -R 65534:65534 /var/ack-ram-authenticator /etc/kubernetes/ack-ram-authenticator`\n\nYou can run this on each master node prior to starting the API server.\nYou could also generate them before provisioning master nodes and install them in the appropriate host paths.\n\nIf you do not pre-generate files, `ack-ram-authenticator server` will generate them on demand.\n\n### 5. Configure your API server to talk to the server\nThe Kubernetes API integrates with ACK RAM Authenticator for Kubernetes using a [token authentication webhook](https://kubernetes.io/docs/admin/authentication/#webhook-token-authentication).\nWhen you run `ack-ram-authenticator server`, it will generate a webhook configuration file and save it onto the host filesystem.\nYou'll need to add a single additional flag to your API server configuration:\n```\n--authentication-token-webhook-config-file=/etc/kubernetes/ack-ram-authenticator/kubeconfig.yaml\n```\n\nOn many clusters, the API server runs as a static pod.\nYou can add the flag to `/etc/kubernetes/manifests/kube-apiserver.yaml`.\nMake sure the host directory `/etc/kubernetes/ack-ram-authenticator/` is mounted into your API server pod.\nYou can run  `sh example-configure-api-server.sh` to automatically complete the above work, example-configure-api-server.sh see [`example-configure-api-server.sh`](deploy/example-configure-api-server.sh).\nYou may also need to restart the kubelet daemon on your master node to pick up the updated static pod definition:\n```\nsystemctl restart kubelet.service\n```\n\u003eNote\n\u003eWhen you restart the ack-ram-authenticator service or regenerate certificate, key, and kubeconfig files, you need run  `sh example-configure-api-server.sh`.\n### 6. Set up kubectl to use authentication tokens provided by ACK RAM Authenticator for Kubernetes\n\n\u003e This requires a 1.10+ `kubectl` binary to work. If you receive `Please enter Username:` when trying to use `kubectl` you need to update to the latest `kubectl`\n\nFinally, once the server is set up you'll want to authenticate!\nYou will still need a `kubeconfig` that has the public data about your cluster (cluster CA certificate, endpoint address).\nThe `users` section of your configuration, however, should include an exec section ([refer to the v1.10 docs](https://kubernetes.io/docs/admin/authentication/#client-go-credential-plugins))::\n```yaml\n# [...]\nusers:\n    - name: \"\u003cyour-user-name\u003e\"\n      user:\n        exec:\n            command: ack-ram-tool\n            args:\n                - credential-plugin\n                - get-token\n                - --cluster-id\n                - \u003cyour-cluster-id\u003e\n                - --api-version\n                - v1beta1\n                - --log-level\n                - error\n            apiVersion: client.authentication.k8s.io/v1beta1\n            provideClusterInfo: false\n            interactiveMode: Never\npreferences: {}\n```\n\nThis means the `kubeconfig` is entirely public data and can be shared across all Authenticator users.\nIt may make sense to upload it to a trusted public location such as AlibabaCloud OSS.\n\nMake sure you have the `ack-ram-tool` binary installed.\nYou can install and configure it with [ack-ram-tool](https://aliyuncontainerservice.github.io/ack-ram-tool/).\n\nTo authenticate, run `kubectl --kubeconfig /path/to/kubeconfig\" [...]`.\nkubectl will `exec` the `ack-ram-tool` binary with the supplied params in your kubeconfig which will generate a token and pass it to the apiserver.\n\n## How does it work?\nIt works using the RAM [`sts:GetCallerIdentity`](https://help.aliyun.com/document_detail/43767.html) API endpoint.\nThis endpoint returns information about whatever RAM credentials you use to connect to it.\n\n#### Client side (`ack-ram-tool credential-plugin get-token`)\nWe use this API in a somewhat unusual way by having the Authenticator client generate and pre-sign a request to the endpoint.\nWe serialize that request into a token that can pass through the Kubernetes authentication system.\n\n#### Server side (`ack-ram-authenticator server`)\nThe token is passed through the Kubernetes API server and into the Authenticator server's `/authenticate` endpoint via a webhook configuration.\nThe Authenticator server validates all the parameters of the pre-signed request to make sure nothing looks funny.\nIt then submits the request to the real `https://sts.aliyuncs.com` server, which validates the client's HMAC signature and returns information about the user.\nNow that the server knows the RAM identity of the client, it translates this identity into a Kubernetes user and groups via a simple static mapping.\n\n## What is a cluster ID?\nThe Authenticator cluster ID is a unique-per-cluster identifier that prevents certain replay attacks.\nSpecifically, it prevents one Authenticator server (e.g., in a dev environment) from using a client's token to authenticate to another Authenticator server in another cluster.\n\n\n## Troubleshooting\n\nIf that fails, there are a few possible problems to check for:\n\n - Make sure your base RAM credentials are available in your shell.\n\n - Make sure the target role allows your source account access (in the role trust policy).\n\n - Make sure your source principal (user/role/group) has an RAM policy that allows `sts:AssumeRole` for the target role.\n\n - Make sure you don't have any explicit deny policies attached to your user, group  that would prevent the `sts:AssumeRole`.\n\n## Full Configuration Format\nThe client and server have the same configuration format.\nThey can share the same exact configuration file, since there are no secrets stored in the configuration.\n\n```yaml\n# a unique-per-cluster identifier to prevent replay attacks (see above)\nclusterID: c1234abcde-xxxx\n\n# default RAM role to assume for `ack-ram-authenticator token`\ndefaultRole: acs:ram::000000000000:role/KubernetesAdmin\n\n# server listener configuration\nserver:\n  # localhost port where the server will serve the /authenticate endpoint\n  port: 21362 # (default)\n\n  # state directory for generated TLS certificate and private keys\n  stateDir: /var/ack-ram-authenticator # (default)\n\n  # output `path` where a generated webhook kubeconfig will be stored.\n  generateKubeconfig: /etc/kubernetes/ack-ram-authenticator.kubeconfig # (default)\n\n  # each mapRoles entry maps an RAM role to a username and set of groups\n  # Each username and group can optionally contain template parameters:\n  #  1) \"{{AccountID}}\" is the 16 digit ID.\n  #  2) \"{{SessionName}}\" is the role session name.\n  mapRoles:\n  # statically map acs:ram::000000000000:role/KubernetesAdmin to cluster admin\n  - roleARN: acs:ram::000000000000:role/KubernetesAdmin\n    username: kubernetes-admin\n    groups:\n    - system:masters\n\n  # each mapUsers entry maps an RAM role to a static username and set of groups\n  mapUsers:\n  # map user RAM user Alice in 000000000000 to user \"alice\" in group \"system:masters\"\n  - userARN: acs:ram::000000000000:user/Alice\n    username: alice\n    groups:\n    - system:masters\n```\n\n## Community, discussion, contribution, and support\n\nYou are welcome to make new issues and pull reuqests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faliyuncontainerservice%2Fack-ram-authenticator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faliyuncontainerservice%2Fack-ram-authenticator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faliyuncontainerservice%2Fack-ram-authenticator/lists"}