Feat: add certificate configuration document #676
Conversation
karmada-bot
added
the
kind/documentation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
|
Welcome @irwin9204! It looks like this is your first PR to karmada-io/website 🎉 |
karmada-bot
added
the
size/XL
irwin9204
force-pushed
the
cert-configuration
branch
from
aa5d224
to
a84d88a
Compare
| | front-proxy-client | front-proxy-client | / | kubernetes.default.svc "*.etcd.karmada-system.svc.cluster.local" "*.karmada-system.svc.cluster.local" "*.karmada-system.svc" "localhost" "127.0.0.1" | | ||
|
|
||
| #### Karmada 组件如何使用证书 | ||
| karmada通过secret来store证书。当前Karmada用于store证书的secret有： |
There was a problem hiding this comment.
| karmada通过secret来store证书。当前Karmada用于store证书的secret有： | |
| karmada通过secret来store证书。当前Karmada用于store证书的secret有： | |
| └── karmada.key | ||
| ``` | ||
|
|
||
| #### **Karmada Certificate Overview** |
There was a problem hiding this comment.
| #### **Karmada Certificate Overview** | |
| #### Karmada Certificate Overview | |
|
|
||
| Certificates can be categorized into three sets based on the issuing CA: | ||
|
|
||
| - Issued by ca |
There was a problem hiding this comment.
| - Issued by ca | |
| - Issued by CA |
There was a problem hiding this comment.
@samzong ca is the name of a CA certificate, similar to etcd-ca and front-proxy-ca.
There was a problem hiding this comment.
How about:
- Issued by CA certificate `ca`|
|
||
| Certificates can be categorized into three sets based on the issuing CA: | ||
|
|
||
| - Issued by ca |
There was a problem hiding this comment.
| - Issued by ca | |
| - Issued by CA |
| title: Certificate Configuration | ||
| --- | ||
|
|
||
| ## Certificate Configuration |
There was a problem hiding this comment.
| ## Certificate Configuration | |
| ## 证书配置 |
| ``` | ||
| #### Karmada 证书简介 | ||
|
|
||
| 依据证书所签发的 CA可以分为三套证书： |
There was a problem hiding this comment.
| 依据证书所签发的 CA可以分为三套证书： | |
| 依据证书所签发的 CA 可以分为三套证书： | |
|
|
||
| 依据证书所签发的 CA可以分为三套证书： | ||
|
|
||
| - 由ca签发 |
There was a problem hiding this comment.
| - 由ca签发 | |
| - 由 CA 签发 |
|
|
||
| - 由ca签发 | ||
|
|
||
| 证书 apiserver和karmada均由CA ca证书签发，证书的关键属性如下： |
There was a problem hiding this comment.
| 证书 apiserver和karmada均由CA ca证书签发，证书的关键属性如下： | |
| 证书 apiserver 和 Karmada 均由 CA 证书签发，证书的关键属性如下： | |
|
|
||
| 可从[cert-secret-generation](https://github.com/karmada-io/karmada/blob/19d1146c3510942809f48d399fc2079ce3a79a66/hack/deploy-karmada.sh#L102-L124) 查找各secret所对应的证书。 | ||
|
|
||
| Karmada 组件通过挂载 secret来获取所需证书，各组件的证书使用详情如下： |
There was a problem hiding this comment.
| Karmada 组件通过挂载 secret来获取所需证书，各组件的证书使用详情如下： | |
| Karmada 组件通过挂载 secret 来获取所需证书，各组件的证书使用详情如下： | |
|
|
||
| - Remaining components can be restarted in the same batch. | ||
|
|
||
| With this, the process of updating expired certificates is complete. |
There was a problem hiding this comment.
| With this, the process of updating expired certificates is complete. | |
| With this, the process of updating expired certificates is completed. |
|
@windsonsea If u have some time, please take a look. |
| - --cert-file=/etc/karmada/pki/etcd-server.crt | ||
| - --key-file=/etc/karmada/pki/etcd-server.key | ||
| - --trusted-ca-file=/etc/karmada/pki/etcd-ca.crt |
There was a problem hiding this comment.
| - --cert-file=/etc/karmada/pki/etcd-server.crt | |
| - --key-file=/etc/karmada/pki/etcd-server.key | |
| - --trusted-ca-file=/etc/karmada/pki/etcd-ca.crt | |
| - --cert-file=/etc/karmada/pki/etcd-server.crt | |
| - --key-file=/etc/karmada/pki/etcd-server.key | |
| - --trusted-ca-file=/etc/karmada/pki/etcd-ca.crt |
These redundant spaces can be removed. Same issue below.
| echo "${apiserver_url}" | awk -F/ '{print $3}' | sed 's/:.*//' | ||
| ``` | ||
|
|
||
| > PS: The `karmada api server config` in the `kubeconfig` file is composed of the `karmada` certificate. |
There was a problem hiding this comment.
| > PS: The `karmada api server config` in the `kubeconfig` file is composed of the `karmada` certificate. | |
| > Note: The `karmada api server config` in the `kubeconfig` file is based on the `karmada` certificate. | |
|
|
||
| - Issued by etcd-ca | ||
|
|
||
| The certificates `etcd-server` and `etcd-client` are both issued by the CA certificate `etcd-ca`. The key attributes of these certificates are as follows: |
There was a problem hiding this comment.
| The certificates `etcd-server` and `etcd-client` are both issued by the CA certificate `etcd-ca`. The key attributes of these certificates are as follows: | |
| The `etcd-server` and `etcd-client` certificates are both issued by `etcd-ca`. Below are the key attributes of these certificates: |
Seems etcd-ca is a CA instead of a certificate.
|
|
||
| The certificates `etcd-server` and `etcd-client` are both issued by the CA certificate `etcd-ca`. The key attributes of these certificates are as follows: | ||
|
|
||
| | certificates | common name(CN) | organization(og) | hosts | |
There was a problem hiding this comment.
| | certificates | common name(CN) | organization(og) | hosts | | |
| | Certificates | Common Name (CN) | Organization (og) | Hosts | |
Should we capitalize the first letter? Same issue below.
|
|
||
| - Issued by front-proxy-ca | ||
|
|
||
| The certificate `front-proxy-client` is issued by the CA certificate `front-proxy-ca`. The key attributes of these certificates are as follows: |
There was a problem hiding this comment.
| The certificate `front-proxy-client` is issued by the CA certificate `front-proxy-ca`. The key attributes of these certificates are as follows: | |
| The `front-proxy-client` certificate is issued by `front-proxy-ca`. Below are the key attributes of this certificate: |
|
|
||
| #### generate a new certificate | ||
|
|
||
| 1. **Determine the issuing CA of the expired certificate.** Refer to the **Karmada Certificate Overview** for the relationship between business certificates and their issuing CAs. |
There was a problem hiding this comment.
| 1. **Determine the issuing CA of the expired certificate.** Refer to the **Karmada Certificate Overview** for the relationship between business certificates and their issuing CAs. | |
| 1. **Determine the issuing CA of the expired certificate.** Refer to the [Karmada Certificate Overview](#karmada-certificate-overview) for the relationship between business certificates and their issuing CAs. |
It's better to provide a link rather than a bold text.
| ... ... | ||
| ``` | ||
|
|
||
| The output of the command indicates that the expired certificate has the following details: `CN=system:admin`, `O=system:masters`, and `hosts=kubernetes.default.svc "*.etcd.karmada-system.svc.cluster.local" "*.karmada-system.svc.cluster.local" "*.karmada-system.svc" "localhost" "127.0.0.1"`. |
There was a problem hiding this comment.
| The output of the command indicates that the expired certificate has the following details: `CN=system:admin`, `O=system:masters`, and `hosts=kubernetes.default.svc "*.etcd.karmada-system.svc.cluster.local" "*.karmada-system.svc.cluster.local" "*.karmada-system.svc" "localhost" "127.0.0.1"`. | |
| The output of the command indicates that the expired certificate has the following details: | |
| - `CN=system:admin` | |
| - `O=system:masters` | |
| - `hosts=kubernetes.default.svc "*.etcd.karmada-system.svc.cluster.local" "*.karmada-system.svc.cluster.local" "*.karmada-system.svc" "localhost" "127.0.0.1"` |
A bullet is useful to list 3 or more items
| ./signCert.sh . "ca" "${HOME}/.karmada" "karmada" "system:admin" "system:masters" kubernetes.default.svc "*.etcd.karmada-system.svc.cluster.local" "*.karmada-system.svc.cluster.local" "*.karmada-system.svc" "localhost" "127.0.0.1" | ||
| ``` | ||
|
|
||
| #### **Certificate Replacement** |
There was a problem hiding this comment.
| #### **Certificate Replacement** | |
| #### Replace Certificate |
Avoid to add bold font to a heading. Use v+n to show it's an action.
|
|
||
| 1. **Update the Secret** | ||
|
|
||
| Using the certificate `karmada` as an example, |
There was a problem hiding this comment.
| Using the certificate `karmada` as an example, | |
| Use the certificate `karmada` as an example: | |
|
|
||
| Since Karmada components obtain certificates by mounting secrets, when a secret is updated, it will automatically synchronize to the component's mount path. Therefore, all that is needed is for the component to restart so that it can load the new certificate. It is recommended to update the server-side certificates first. This is because updating server-side certificates may affect all clients that depend on that service, whereas client-side certificate updates are more scattered and have a smaller impact range. | ||
|
|
||
| 1. **Update the Secret** |
There was a problem hiding this comment.
| 1. **Update the Secret** | |
| 1. Update the Secret |
Avoid to use bold text everywhere.
|
|
||
| #### **Karmada Certificate Overview** | ||
|
|
||
| Certificates can be categorized into three sets based on the issuing CA: |
There was a problem hiding this comment.
@zhzhuang-zju Do you know why we need 3 CAs to sign the certificates? Can we use just one CA?
There was a problem hiding this comment.
Using three separate CA certificates for issuance is based on roughly dividing the certificates according to their primary functions. Issuing with three separate CAs can increase isolation between the certificates. If we adjust to using a single CA, the functionality can still be achieved.
What type of PR is this?
/kind documentation
What this PR does / why we need it:
Help users to configure certificates that use in karmada control plane
Which issue(s) this PR fixes:
Part of karmada-io/karmada#4787
Special notes for your reviewer:
None