Merge pull request #50002 from sftim/20250303_csr_refactor_task
Move CSR for client certificate to tasks sectionpull/50072/head
Kubernetes Prow Robot
GitHub
commit
1465f01652
|
|
@ -33,9 +33,7 @@ presents a valid certificate signed by the cluster's certificate authority
|
|||
the username from the common name field in the 'subject' of the cert (e.g.,
|
||||
"/CN=bob"). From there, the role based access control (RBAC) sub-system would
|
||||
determine whether the user is authorized to perform a specific operation on a
|
||||
resource. For more details, refer to the normal users topic in
|
||||
[certificate request](/docs/reference/access-authn-authz/certificate-signing-requests/#normal-user)
|
||||
for more details about this.
|
||||
resource.
|
||||
|
||||
In contrast, service accounts are users managed by the Kubernetes API. They are
|
||||
bound to specific namespaces, and created automatically by the API server or
|
||||
|
|
@ -1815,5 +1813,6 @@ You can only make `SelfSubjectReview` requests if:
|
|||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* To learn about issuing certificates for users, read [Issue a Certificate for a Kubernetes API Client Using A CertificateSigningRequest](/docs/tasks/tls/certificate-issue-client-csr/)
|
||||
* Read the [client authentication reference (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/)
|
||||
* Read the [client authentication reference (v1)](/docs/reference/config-api/client-authentication.v1/)
|
||||
|
|
|
|||
|
|
@ -489,133 +489,10 @@ signer-unlinked ClusterTrustBundles **must not** contain a colon (`:`).
|
|||
The contents of ClusterTrustBundles can be injected into the container filesystem, similar to ConfigMaps and Secrets.
|
||||
See the [clusterTrustBundle projected volume source](/docs/concepts/storage/projected-volumes#clustertrustbundle) for more details.
|
||||
|
||||
<!-- TODO this should become a task page -->
|
||||
## How to issue a certificate for a user {#normal-user}
|
||||
|
||||
A few steps are required in order to get a normal user to be able to
|
||||
authenticate and invoke an API. First, this user must have a certificate issued
|
||||
by the Kubernetes cluster, and then present that certificate to the Kubernetes API.
|
||||
|
||||
### Create private key
|
||||
|
||||
The following scripts show how to generate PKI private key and CSR. It is
|
||||
important to set CN and O attribute of the CSR. CN is the name of the user and
|
||||
O is the group that this user will belong to. You can refer to
|
||||
[RBAC](/docs/reference/access-authn-authz/rbac/) for standard groups.
|
||||
|
||||
```shell
|
||||
openssl genrsa -out myuser.key 2048
|
||||
openssl req -new -key myuser.key -out myuser.csr -subj "/CN=myuser"
|
||||
```
|
||||
|
||||
### Create a CertificateSigningRequest {#create-certificatessigningrequest}
|
||||
|
||||
Create a [CertificateSigningRequest](/docs/reference/kubernetes-api/authentication-resources/certificate-signing-request-v1/)
|
||||
and submit it to a Kubernetes Cluster via kubectl. Below is a script to generate the
|
||||
CertificateSigningRequest.
|
||||
|
||||
```shell
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: certificates.k8s.io/v1
|
||||
kind: CertificateSigningRequest
|
||||
metadata:
|
||||
name: myuser
|
||||
spec:
|
||||
request: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQ1ZqQ0NBVDRDQVFBd0VURVBNQTBHQTFVRUF3d0dZVzVuWld4aE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRgpBQU9DQVE4QU1JSUJDZ0tDQVFFQTByczhJTHRHdTYxakx2dHhWTTJSVlRWMDNHWlJTWWw0dWluVWo4RElaWjBOCnR2MUZtRVFSd3VoaUZsOFEzcWl0Qm0wMUFSMkNJVXBGd2ZzSjZ4MXF3ckJzVkhZbGlBNVhwRVpZM3ExcGswSDQKM3Z3aGJlK1o2MVNrVHF5SVBYUUwrTWM5T1Nsbm0xb0R2N0NtSkZNMUlMRVI3QTVGZnZKOEdFRjJ6dHBoaUlFMwpub1dtdHNZb3JuT2wzc2lHQ2ZGZzR4Zmd4eW8ybmlneFNVekl1bXNnVm9PM2ttT0x1RVF6cXpkakJ3TFJXbWlECklmMXBMWnoyalVnald4UkhCM1gyWnVVV1d1T09PZnpXM01LaE8ybHEvZi9DdS8wYk83c0x0MCt3U2ZMSU91TFcKcW90blZtRmxMMytqTy82WDNDKzBERHk5aUtwbXJjVDBnWGZLemE1dHJRSURBUUFCb0FBd0RRWUpLb1pJaHZjTgpBUUVMQlFBRGdnRUJBR05WdmVIOGR4ZzNvK21VeVRkbmFjVmQ1N24zSkExdnZEU1JWREkyQTZ1eXN3ZFp1L1BVCkkwZXpZWFV0RVNnSk1IRmQycVVNMjNuNVJsSXJ3R0xuUXFISUh5VStWWHhsdnZsRnpNOVpEWllSTmU3QlJvYXgKQVlEdUI5STZXT3FYbkFvczFqRmxNUG5NbFpqdU5kSGxpT1BjTU1oNndLaTZzZFhpVStHYTJ2RUVLY01jSVUyRgpvU2djUWdMYTk0aEpacGk3ZnNMdm1OQUxoT045UHdNMGM1dVJVejV4T0dGMUtCbWRSeEgvbUNOS2JKYjFRQm1HCkkwYitEUEdaTktXTU0xMzhIQXdoV0tkNjVoVHdYOWl4V3ZHMkh4TG1WQzg0L1BHT0tWQW9FNkpsYWFHdTlQVmkKdjlOSjVaZlZrcXdCd0hKbzZXdk9xVlA3SVFjZmg3d0drWm89Ci0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo=
|
||||
signerName: kubernetes.io/kube-apiserver-client
|
||||
expirationSeconds: 86400 # one day
|
||||
usages:
|
||||
- client auth
|
||||
EOF
|
||||
```
|
||||
|
||||
Some points to note:
|
||||
|
||||
- `usages` has to be '`client auth`'
|
||||
- `expirationSeconds` could be made longer (i.e. `864000` for ten days) or shorter (i.e. `3600` for one hour)
|
||||
- `request` is the base64 encoded value of the CSR file content.
|
||||
You can get the content using this command:
|
||||
|
||||
```shell
|
||||
cat myuser.csr | base64 | tr -d "\n"
|
||||
```
|
||||
|
||||
|
||||
### Approve the CertificateSigningRequest {#approve-certificate-signing-request}
|
||||
|
||||
Use kubectl to create a CSR and approve it.
|
||||
|
||||
Get the list of CSRs:
|
||||
|
||||
```shell
|
||||
kubectl get csr
|
||||
```
|
||||
|
||||
Approve the CSR:
|
||||
|
||||
```shell
|
||||
kubectl certificate approve myuser
|
||||
```
|
||||
|
||||
### Get the certificate
|
||||
|
||||
Retrieve the certificate from the CSR:
|
||||
|
||||
```shell
|
||||
kubectl get csr/myuser -o yaml
|
||||
```
|
||||
|
||||
The certificate value is in Base64-encoded format under `status.certificate`.
|
||||
|
||||
Export the issued certificate from the CertificateSigningRequest.
|
||||
|
||||
```shell
|
||||
kubectl get csr myuser -o jsonpath='{.status.certificate}'| base64 -d > myuser.crt
|
||||
```
|
||||
|
||||
### Create Role and RoleBinding
|
||||
|
||||
With the certificate created it is time to define the Role and RoleBinding for
|
||||
this user to access Kubernetes cluster resources.
|
||||
|
||||
This is a sample command to create a Role for this new user:
|
||||
|
||||
```shell
|
||||
kubectl create role developer --verb=create --verb=get --verb=list --verb=update --verb=delete --resource=pods
|
||||
```
|
||||
|
||||
This is a sample command to create a RoleBinding for this new user:
|
||||
|
||||
```shell
|
||||
kubectl create rolebinding developer-binding-myuser --role=developer --user=myuser
|
||||
```
|
||||
|
||||
### Add to kubeconfig
|
||||
|
||||
The last step is to add this user into the kubeconfig file.
|
||||
|
||||
First, you need to add new credentials:
|
||||
|
||||
```shell
|
||||
kubectl config set-credentials myuser --client-key=myuser.key --client-certificate=myuser.crt --embed-certs=true
|
||||
|
||||
```
|
||||
|
||||
Then, you need to add the context:
|
||||
|
||||
```shell
|
||||
kubectl config set-context myuser --cluster=kubernetes --user=myuser
|
||||
```
|
||||
|
||||
To test it, change the context to `myuser`:
|
||||
|
||||
```shell
|
||||
kubectl config use-context myuser
|
||||
```
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* Read [Manage TLS Certificates in a Cluster](/docs/tasks/tls/managing-tls-in-a-cluster/)
|
||||
* Read [Issue a Certificate for a Kubernetes API Client Using A CertificateSigningRequest](/docs/tasks/tls/certificate-issue-client-csr/)
|
||||
* View the source code for the kube-controller-manager built in
|
||||
[signer](https://github.com/kubernetes/kubernetes/blob/32ec6c212ec9415f604ffc1f4c1f29b782968ff1/pkg/controller/certificates/signer/cfssl_signer.go)
|
||||
* View the source code for the kube-controller-manager built in
|
||||
|
|
|
|||
|
|
@ -0,0 +1,185 @@
|
|||
---
|
||||
title: Issue a Certificate for a Kubernetes API Client Using A CertificateSigningRequest
|
||||
api_metadata:
|
||||
- apiVersion: "certificates.k8s.io/v1"
|
||||
kind: "CertificateSigningRequest"
|
||||
override_link_text: "CSR v1"
|
||||
weight: 80
|
||||
|
||||
# Docs maintenance note
|
||||
#
|
||||
# If there is a future page /docs/tasks/tls/certificate-issue-client-manually/ then this page
|
||||
# should link there, and the new page should link back to this one.
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
Kubernetes lets you use a public key infrastructure (PKI) to authenticate to your cluster
|
||||
as a client.
|
||||
|
||||
A few steps are required in order to get a normal user to be able to
|
||||
authenticate and invoke an API. First, this user must have an [X.509](https://www.itu.int/rec/T-REC-X.509) certificate
|
||||
issued by an authority that your Kubernetes cluster trusts. The client must then present that certificate to the Kubernetes API.
|
||||
|
||||
You use a [CertificateSigningRequest](/concepts/security/certificate-signing-requests/)
|
||||
as part of this process, and either you or some other principal must approve the request.
|
||||
|
||||
|
||||
You will create a private key, and then get a certificate issued, and finally configure
|
||||
that private key for a client.
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
* {{< include "task-tutorial-prereqs.md" >}}
|
||||
|
||||
* You need the `kubectl`, `openssl` and `base64` utilities.
|
||||
|
||||
This page assumes you are using Kubernetes {{< glossary_tooltip term_id="rbac" text="role based access control" >}} (RBAC).
|
||||
If you have alternative or additional security mechanisms around authorization, you need to account for those as well.
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
## Create private key
|
||||
|
||||
In this step, you create a private key. You need to keep this document secret; anyone who has it can impersonate the user.
|
||||
|
||||
```shell
|
||||
# Create a private key
|
||||
openssl genrsa -out myuser.key 3072
|
||||
```
|
||||
|
||||
## Create an X.509 certificate signing request {#create-x.509-certificatessigningrequest}
|
||||
|
||||
{{< note >}}
|
||||
This is not the same as the similarly-named CertificateSigningRequest API; the file you generate here goes into the
|
||||
CertificateSigningRequest.
|
||||
{{< /note >}}
|
||||
|
||||
It is important to set CN and O attribute of the CSR. CN is the name of the user and O is the group that this user will belong to.
|
||||
You can refer to [RBAC](/docs/reference/access-authn-authz/rbac/) for standard groups.
|
||||
|
||||
```shell
|
||||
# Change the common name "myuser" to the actual username that you want to use
|
||||
openssl req -new -key myuser.key -out myuser.csr -subj "/CN=myuser"
|
||||
```
|
||||
|
||||
## Create a Kubernetes CertificateSigningRequest {#create-k8s-certificatessigningrequest}
|
||||
|
||||
Encode the CSR document using this command:
|
||||
|
||||
```shell
|
||||
cat myuser.csr | base64 | tr -d "\n"
|
||||
```
|
||||
|
||||
Create a [CertificateSigningRequest](/docs/reference/kubernetes-api/authentication-resources/certificate-signing-request-v1/)
|
||||
and submit it to a Kubernetes Cluster via kubectl. Below is a snippet of shell that you can use to generate the
|
||||
CertificateSigningRequest.
|
||||
|
||||
```shell
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: certificates.k8s.io/v1
|
||||
kind: CertificateSigningRequest
|
||||
metadata:
|
||||
name: myuser # example
|
||||
spec:
|
||||
# This is an encoded CSR. Change this to the base64-encoded contents of myuser.csr
|
||||
request: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQ1ZqQ0NBVDRDQVFBd0VURVBNQTBHQTFVRUF3d0dZVzVuWld4aE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRgpBQU9DQVE4QU1JSUJDZ0tDQVFFQTByczhJTHRHdTYxakx2dHhWTTJSVlRWMDNHWlJTWWw0dWluVWo4RElaWjBOCnR2MUZtRVFSd3VoaUZsOFEzcWl0Qm0wMUFSMkNJVXBGd2ZzSjZ4MXF3ckJzVkhZbGlBNVhwRVpZM3ExcGswSDQKM3Z3aGJlK1o2MVNrVHF5SVBYUUwrTWM5T1Nsbm0xb0R2N0NtSkZNMUlMRVI3QTVGZnZKOEdFRjJ6dHBoaUlFMwpub1dtdHNZb3JuT2wzc2lHQ2ZGZzR4Zmd4eW8ybmlneFNVekl1bXNnVm9PM2ttT0x1RVF6cXpkakJ3TFJXbWlECklmMXBMWnoyalVnald4UkhCM1gyWnVVV1d1T09PZnpXM01LaE8ybHEvZi9DdS8wYk83c0x0MCt3U2ZMSU91TFcKcW90blZtRmxMMytqTy82WDNDKzBERHk5aUtwbXJjVDBnWGZLemE1dHJRSURBUUFCb0FBd0RRWUpLb1pJaHZjTgpBUUVMQlFBRGdnRUJBR05WdmVIOGR4ZzNvK21VeVRkbmFjVmQ1N24zSkExdnZEU1JWREkyQTZ1eXN3ZFp1L1BVCkkwZXpZWFV0RVNnSk1IRmQycVVNMjNuNVJsSXJ3R0xuUXFISUh5VStWWHhsdnZsRnpNOVpEWllSTmU3QlJvYXgKQVlEdUI5STZXT3FYbkFvczFqRmxNUG5NbFpqdU5kSGxpT1BjTU1oNndLaTZzZFhpVStHYTJ2RUVLY01jSVUyRgpvU2djUWdMYTk0aEpacGk3ZnNMdm1OQUxoT045UHdNMGM1dVJVejV4T0dGMUtCbWRSeEgvbUNOS2JKYjFRQm1HCkkwYitEUEdaTktXTU0xMzhIQXdoV0tkNjVoVHdYOWl4V3ZHMkh4TG1WQzg0L1BHT0tWQW9FNkpsYWFHdTlQVmkKdjlOSjVaZlZrcXdCd0hKbzZXdk9xVlA3SVFjZmg3d0drWm89Ci0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo=
|
||||
signerName: kubernetes.io/kube-apiserver-client
|
||||
expirationSeconds: 86400 # one day
|
||||
usages:
|
||||
- client auth
|
||||
EOF
|
||||
```
|
||||
|
||||
Some points to note:
|
||||
|
||||
- `usages` has to be `client auth`
|
||||
- `expirationSeconds` could be made longer (i.e. `864000` for ten days) or shorter (i.e. `3600` for one hour).
|
||||
You cannot request a duration shorter than 10 minutes.
|
||||
- `request` is the base64 encoded value of the CSR file content.
|
||||
|
||||
## Approve the CertificateSigningRequest {#approve-certificate-signing-request}
|
||||
|
||||
Use kubectl to find the CSR you made, and manually approve it.
|
||||
|
||||
Get the list of CSRs:
|
||||
|
||||
```shell
|
||||
kubectl get csr
|
||||
```
|
||||
|
||||
Approve the CSR:
|
||||
|
||||
```shell
|
||||
kubectl certificate approve myuser
|
||||
```
|
||||
|
||||
## Get the certificate
|
||||
|
||||
Retrieve the certificate from the CSR, to check it looks OK.
|
||||
|
||||
```shell
|
||||
kubectl get csr/myuser -o yaml
|
||||
```
|
||||
|
||||
The certificate value is in Base64-encoded format under `.status.certificate`.
|
||||
|
||||
Export the issued certificate from the CertificateSigningRequest.
|
||||
|
||||
```shell
|
||||
kubectl get csr myuser -o jsonpath='{.status.certificate}'| base64 -d > myuser.crt
|
||||
```
|
||||
|
||||
## Configure the certificate into kubeconfig
|
||||
|
||||
The next step is to add this user into the kubeconfig file.
|
||||
|
||||
First, you need to add new credentials:
|
||||
|
||||
```shell
|
||||
kubectl config set-credentials myuser --client-key=myuser.key --client-certificate=myuser.crt --embed-certs=true
|
||||
|
||||
```
|
||||
|
||||
Then, you need to add the context:
|
||||
|
||||
```shell
|
||||
kubectl config set-context myuser --cluster=kubernetes --user=myuser
|
||||
```
|
||||
|
||||
To test it:
|
||||
|
||||
```shell
|
||||
kubectl --context myuser auth whoami
|
||||
```
|
||||
|
||||
You should see output confirming that you are “myuser“.
|
||||
|
||||
## Create Role and RoleBinding
|
||||
|
||||
{{< note >}}
|
||||
If you don't use Kubernetes RBAC, skip this step and make the appropriate changes for the authorization mechanism
|
||||
your cluster actually uses.
|
||||
{{< /note >}}
|
||||
|
||||
With the certificate created it is time to define the Role and RoleBinding for
|
||||
this user to access Kubernetes cluster resources.
|
||||
|
||||
This is a sample command to create a Role for this new user:
|
||||
|
||||
```shell
|
||||
kubectl create role developer --verb=create --verb=get --verb=list --verb=update --verb=delete --resource=pods
|
||||
```
|
||||
|
||||
This is a sample command to create a RoleBinding for this new user:
|
||||
|
||||
```shell
|
||||
kubectl create rolebinding developer-binding-myuser --role=developer --user=myuser
|
||||
```
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* Read [Manage TLS Certificates in a Cluster](/docs/tasks/tls/managing-tls-in-a-cluster/)
|
||||
* For details of X.509 itself, refer to [RFC 5280](https://tools.ietf.org/html/rfc5280#section-3.1) section 3.1
|
||||
* For information on the syntax of PKCS#10 certificate signing requests, refer to [RFC 2986](https://tools.ietf.org/html/rfc2986)
|
||||
* Read about [ClusterTrustBundles](/docs/reference/access-authn-authz/certificate-signing-requests/#cluster-trust-bundles)
|
||||
Loading…
Reference in New Issue