From 9ba85a0409b71b5012590e67aafdecea96b36a10 Mon Sep 17 00:00:00 2001 From: Rohan CJ Date: Thu, 5 Dec 2024 19:29:37 +0530 Subject: [PATCH 1/4] feat: document cert-manager integration Signed-off-by: Rohan CJ --- .../_fragments/integrations/cert-manager.mdx | 80 +++++++++++++++++++ .../integrations/cert-manager.mdx | 13 +++ .../cert-manager/cert-manager.mdx | 11 +++ 3 files changed, 104 insertions(+) create mode 100644 vcluster/_fragments/integrations/cert-manager.mdx create mode 100644 vcluster/configure/vcluster-yaml/integrations/cert-manager.mdx create mode 100644 vcluster/integrations/cert-manager/cert-manager.mdx diff --git a/vcluster/_fragments/integrations/cert-manager.mdx b/vcluster/_fragments/integrations/cert-manager.mdx new file mode 100644 index 000000000..8b17548b7 --- /dev/null +++ b/vcluster/_fragments/integrations/cert-manager.mdx @@ -0,0 +1,80 @@ +import CodeBlock from '@theme/CodeBlock'; + +import Deploy from '../../_partials/deploy/deploy.mdx' +import ProAdmonition from '../../_partials/admonitions/pro-admonition.mdx' +import MetricsServer from '../../_partials/config/integrations/certManager.mdx' + + + +### Prerequisites +This guide assumes you have the following prerequisites: +- `kubectl` installed +- `cert-manager` operator installed on your host cluster. See instructions at https://cert-manager.io +

+ +# Certificate Manager Integration + +To enable the cert-manager integration, set the following fields as shown below: + +```yaml +integrations: + certManager: + enabled: true +``` + +This will enable the integration, import cluster scoped ClusterIssuers from the host cluster into the virtual cluster and export namespaced Issuers and Certificates from the virtual cluster into the host cluster. + +Once that the virtual cluster is up and running, you can create a Issuer and Certificate inside the virtual cluster. For the purpose of this guide, we will use a `letsencrypt-staging` issuer. + +```yaml +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: letsencrypt-staging +spec: + acme: + # You must replace this email address with your own. + # Let's Encrypt will use this to contact you about expiring + # certificates, and issues related to your account. + email: user@example.com + server: https://acme-staging-v02.api.letsencrypt.org/directory + privateKeySecretRef: + # Secret resource that will be used to store the account's private key. + name: example-issuer-account-key + # Add a single challenge solver, HTTP01 using nginx + solvers: + - http01: + ingress: + ingressClassName: nginx + +``` + + + +Inside the virtual cluster, create the store with `kubectl apply -f issuer.yaml`. This should create a corresponding Issuer in the host cluster. You can then observe the status of the Issuer in the virtual cluster, and create a Certificate object. + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: quickstart-example-tls + namespace: default +spec: + dnsNames: + - example.example.com + issuerRef: + group: cert-manager.io + kind: Issuer + name: letsencrypt-staging + secretName: quickstart-example-tls + usages: + - digital signature + - key encipherment +``` + +Once that certificate is created in the virtual cluster, the integration will sync the created secret back to the virtual cluster after the cert-manager operator creates it in the host cluster, and the certificate is ready to use. + + +### Config Reference + + \ No newline at end of file diff --git a/vcluster/configure/vcluster-yaml/integrations/cert-manager.mdx b/vcluster/configure/vcluster-yaml/integrations/cert-manager.mdx new file mode 100644 index 000000000..f767574d8 --- /dev/null +++ b/vcluster/configure/vcluster-yaml/integrations/cert-manager.mdx @@ -0,0 +1,13 @@ +--- +title: Certifcate Manager +sidebar_label: certificateManager +sidebar_class_name: pro +sidebar_position: 2 +--- + +import ExternalSecretsGuide from '@site/vcluster/_fragments/integrations/cert-manager.mdx' + + + +## Config Reference + diff --git a/vcluster/integrations/cert-manager/cert-manager.mdx b/vcluster/integrations/cert-manager/cert-manager.mdx new file mode 100644 index 000000000..ea9851f1a --- /dev/null +++ b/vcluster/integrations/cert-manager/cert-manager.mdx @@ -0,0 +1,11 @@ +--- +title: Cert Manager +sidebar_label: Cert Manager +sidebar_class_name: pro +sidebar_position: 2 +--- + +import KubeVirt from '../../_fragments/integrations/cert-manager.mdx' + + + From 332d76dd4578680e8bab96b6f756f01e457b32d0 Mon Sep 17 00:00:00 2001 From: Piotr Zaniewski Date: Mon, 16 Dec 2024 13:22:39 +0100 Subject: [PATCH 2/4] feat: cert manager integration - fixing links and doc structure - adding more details about cert manager integration - vale and styling fixes Signed-off-by: Piotr Zaniewski --- .../_fragments/integrations/cert-manager.mdx | 147 ++++++++++++++++-- .../config/integrations/certManager.mdx | 1 + .../integrations/cert-manager.mdx | 2 +- .../cert-manager/cert-manager.mdx | 11 -- .../integrations/certmanager/certManager.mdx | 10 ++ 5 files changed, 144 insertions(+), 27 deletions(-) create mode 100644 vcluster/_partials/config/integrations/certManager.mdx delete mode 100644 vcluster/integrations/cert-manager/cert-manager.mdx create mode 100644 vcluster/integrations/certmanager/certManager.mdx diff --git a/vcluster/_fragments/integrations/cert-manager.mdx b/vcluster/_fragments/integrations/cert-manager.mdx index 8b17548b7..d6d964f2e 100644 --- a/vcluster/_fragments/integrations/cert-manager.mdx +++ b/vcluster/_fragments/integrations/cert-manager.mdx @@ -1,41 +1,59 @@ +import Flow, { Step } from '@site/src/components/Flow' +import NavStep from '@site/src/components/NavStep' +import Button from '@site/src/components/Button' +import Label from '@site/src/components/Label' +import Field from '@site/src/components/Field' + +import CertManagerPartial from '../../_partials/config/integrations/certManager.mdx'; + +import BasePrerequisites from '../../../platform/_partials/install/base-prerequisites.mdx'; + import CodeBlock from '@theme/CodeBlock'; import Deploy from '../../_partials/deploy/deploy.mdx' + import ProAdmonition from '../../_partials/admonitions/pro-admonition.mdx' -import MetricsServer from '../../_partials/config/integrations/certManager.mdx' ### Prerequisites -This guide assumes you have the following prerequisites: -- `kubectl` installed + + + - `cert-manager` operator installed on your host cluster. See instructions at https://cert-manager.io -

-# Certificate Manager Integration +## Cert manager integration To enable the cert-manager integration, set the following fields as shown below: -```yaml + +```yaml title="Enable cert-manager integration" integrations: certManager: enabled: true ``` -This will enable the integration, import cluster scoped ClusterIssuers from the host cluster into the virtual cluster and export namespaced Issuers and Certificates from the virtual cluster into the host cluster. +This configuration enables the integration, imports cluster-scoped ClusterIssuers from the host cluster into the virtual cluster, and exports namespaced Issuers and Certificates from the virtual cluster into the host cluster. + + + + + Create the Issuer -Once that the virtual cluster is up and running, you can create a Issuer and Certificate inside the virtual cluster. For the purpose of this guide, we will use a `letsencrypt-staging` issuer. +Create a named `issuer.yaml` with the following content: -```yaml +```yaml title="ClusterIssuer configuration" apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: letsencrypt-staging spec: acme: - # You must replace this email address with your own. + # highlight-start + # Replace this email address with your own. # Let's Encrypt will use this to contact you about expiring # certificates, and issues related to your account. + # highlight-end email: user@example.com server: https://acme-staging-v02.api.letsencrypt.org/directory privateKeySecretRef: @@ -46,14 +64,34 @@ spec: - http01: ingress: ingressClassName: nginx +``` + + + +Apply the Issuer configuration: +```bash title="Apply the Issuer configuration" +kubectl apply -f issuer.yaml ``` +:::note +This creates a corresponding Issuer in the host cluster. +::: + + + + +Create and apply Issuer and Certificate +After the virtual cluster is running, create an Issuer and Certificate inside the virtual cluster. This guide uses a `letsencrypt-staging` issuer for demonstration purposes. + -Inside the virtual cluster, create the store with `kubectl apply -f issuer.yaml`. This should create a corresponding Issuer in the host cluster. You can then observe the status of the Issuer in the virtual cluster, and create a Certificate object. + +Create the Certificate -```yaml +Create a file named `certificate.yaml` with the following content: + +```yaml title="Certificate configuration" apiVersion: cert-manager.io/v1 kind: Certificate metadata: @@ -71,10 +109,89 @@ spec: - digital signature - key encipherment ``` + + +Apply the Certificate configuration: + +```bash title="Apply the Certificate configuration" +kubectl apply -f certificate.yaml +``` + +:::tip +After the certificate is created in the virtual cluster, the integration syncs the created secret back to the virtual cluster after the cert-manager operator creates it in the host cluster. +::: + + + + +## Verify the integration + + + +Check the status of the Issuer: + + ```bash title="Check Issuer status" + kubectl describe clusterissuer letsencrypt-staging + ``` + + + +Check the status of the Certificate: + + ```bash title="Check Certificate status" + kubectl describe certificate quickstart-example-tls + ``` + + +Verify that the secret containing the certificate has been created: + + ```bash title="Verify secret creation" + kubectl get secret quickstart-example-tls + ``` + + + + +## Using the certificate in an application + +To use the created certificate in an application, reference the secret in your Ingress resource: + +```yaml title="Example Ingress using the certificate" +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: example-ingress + annotations: + kubernetes.io/ingress.class: nginx +spec: + tls: + - hosts: + - example.example.com + secretName: quickstart-example-tls + rules: + - host: example.example.com + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: example-service + port: + number: 80 +``` + +## Troubleshooting + +If you encounter issues with the cert-manager integration, consider the following: -Once that certificate is created in the virtual cluster, the integration will sync the created secret back to the virtual cluster after the cert-manager operator creates it in the host cluster, and the certificate is ready to use. +- Ensure that cert-manager is properly installed and running in the host cluster. +- Check the cert-manager logs in the host cluster for any error messages. +- Verify that the Issuer and Certificate resources are correctly configured. +- Ensure that the virtual cluster has the necessary permissions to create and manage certificates. +For more detailed troubleshooting, refer to the [cert-manager troubleshooting guide](https://cert-manager.io/docs/troubleshooting/). -### Config Reference +## Config reference - \ No newline at end of file + diff --git a/vcluster/_partials/config/integrations/certManager.mdx b/vcluster/_partials/config/integrations/certManager.mdx new file mode 100644 index 000000000..e244d3215 --- /dev/null +++ b/vcluster/_partials/config/integrations/certManager.mdx @@ -0,0 +1 @@ +## Cert manager diff --git a/vcluster/configure/vcluster-yaml/integrations/cert-manager.mdx b/vcluster/configure/vcluster-yaml/integrations/cert-manager.mdx index f767574d8..087ace9a4 100644 --- a/vcluster/configure/vcluster-yaml/integrations/cert-manager.mdx +++ b/vcluster/configure/vcluster-yaml/integrations/cert-manager.mdx @@ -9,5 +9,5 @@ import ExternalSecretsGuide from '@site/vcluster/_fragments/integrations/cert-ma -## Config Reference +## Config reference diff --git a/vcluster/integrations/cert-manager/cert-manager.mdx b/vcluster/integrations/cert-manager/cert-manager.mdx deleted file mode 100644 index ea9851f1a..000000000 --- a/vcluster/integrations/cert-manager/cert-manager.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Cert Manager -sidebar_label: Cert Manager -sidebar_class_name: pro -sidebar_position: 2 ---- - -import KubeVirt from '../../_fragments/integrations/cert-manager.mdx' - - - diff --git a/vcluster/integrations/certmanager/certManager.mdx b/vcluster/integrations/certmanager/certManager.mdx new file mode 100644 index 000000000..b52f11d58 --- /dev/null +++ b/vcluster/integrations/certmanager/certManager.mdx @@ -0,0 +1,10 @@ +--- +title: "Cert Manager" +sidebar_label: "Cert Manager" +sidebar_class_name: pro +sidebar_position: 2 +--- + +import CertManager from '../../_fragments/integrations/cert-manager.mdx' + + From c16c1b9894adf74bae520461803a59bfe43a00a5 Mon Sep 17 00:00:00 2001 From: Piotr Zaniewski Date: Tue, 17 Dec 2024 11:35:32 +0100 Subject: [PATCH 3/4] chore: add colors options to the Highlight component This is backwards compatible and will not break other usages of the component. Signed-off-by: Piotr Zaniewski --- src/components/Highlight/Highlight.js | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/src/components/Highlight/Highlight.js b/src/components/Highlight/Highlight.js index 6a6a96a7d..64342829b 100644 --- a/src/components/Highlight/Highlight.js +++ b/src/components/Highlight/Highlight.js @@ -1,10 +1,28 @@ import React from 'react'; import styles from './styles.module.css'; +const colors = { + primary: 'var(--ifm-color-primary)', + secondary: 'var(--ifm-color-secondary)', + success: 'var(--ifm-color-success)', + info: 'var(--ifm-color-info)', + warning: 'var(--ifm-color-warning)', + danger: 'var(--ifm-color-danger)' +}; + export default class Highlight extends React.Component { render() { - let {children, ...highlightStyle} = this.props - - return {children} ; + const { children, color, className, ...props } = this.props; + return ( + + {children} + + ); } } \ No newline at end of file From 358e079100c76395d333c0bef7146235599f4320 Mon Sep 17 00:00:00 2001 From: Piotr Zaniewski Date: Tue, 17 Dec 2024 11:35:59 +0100 Subject: [PATCH 4/4] chore: address PR feedback - address feedback - improve usability and commands flow Signed-off-by: Piotr Zaniewski --- .../_fragments/integrations/cert-manager.mdx | 212 ++++++++++-------- 1 file changed, 122 insertions(+), 90 deletions(-) diff --git a/vcluster/_fragments/integrations/cert-manager.mdx b/vcluster/_fragments/integrations/cert-manager.mdx index d6d964f2e..2c5ec3cb0 100644 --- a/vcluster/_fragments/integrations/cert-manager.mdx +++ b/vcluster/_fragments/integrations/cert-manager.mdx @@ -1,31 +1,35 @@ -import Flow, { Step } from '@site/src/components/Flow' -import NavStep from '@site/src/components/NavStep' -import Button from '@site/src/components/Button' -import Label from '@site/src/components/Label' -import Field from '@site/src/components/Field' +import Highlight from "@site/src/components/Highlight/Highlight"; -import CertManagerPartial from '../../_partials/config/integrations/certManager.mdx'; +import Flow, { Step } from "@site/src/components/Flow"; +import NavStep from "@site/src/components/NavStep"; +import Field from "@site/src/components/Field"; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; -import BasePrerequisites from '../../../platform/_partials/install/base-prerequisites.mdx'; +import CertManagerPartial from "../../_partials/config/integrations/certManager.mdx"; +import BasePrerequisites from "../../../platform/_partials/install/base-prerequisites.mdx"; +import CodeBlock from "@theme/CodeBlock"; +import Deploy from "../../_partials/deploy/deploy.mdx"; +import ProAdmonition from "../../_partials/admonitions/pro-admonition.mdx"; -import CodeBlock from '@theme/CodeBlock'; + -import Deploy from '../../_partials/deploy/deploy.mdx' +# Cert manager integration -import ProAdmonition from '../../_partials/admonitions/pro-admonition.mdx' - - +This guide shows how to set up cert-manager integration with your virtual cluster. ### Prerequisites -- `cert-manager` operator installed on your host cluster. See instructions at https://cert-manager.io +- `cert-manager` operator installed on your host cluster, see [cert-manager installation + guide](https://cert-manager.io). -## Cert manager integration +## Enable the integration -To enable the cert-manager integration, set the following fields as shown below: + +Enable the cert-manager integration in your virtual cluster configuration: ```yaml title="Enable cert-manager integration" integrations: @@ -33,16 +37,50 @@ integrations: enabled: true ``` -This configuration enables the integration, imports cluster-scoped ClusterIssuers from the host cluster into the virtual cluster, and exports namespaced Issuers and Certificates from the virtual cluster into the host cluster. +This configuration: + +- Enables the integration. +- Imports cluster-scoped `ClusterIssuers` from your host cluster into the virtual + cluster. +- Exports namespaced Issuers and Certificates from the virtual cluster to the + host cluster. + +:::tip create virtual cluster +Create or update a `virtual Cluster` following the [vCluster quick start +guide](/vcluster#deploy-vcluster). +::: + +### Set up cluster contexts + +Setting up the host and virtual cluster contexts makes it easier to switch +between them. + +```bash +export HOST_CTX="your-host-context" +export VCLUSTER_CTX="vcluster-ctx" +``` + +:::tip +You can find your contexts by running `kubectl config get-contexts` +::: + +## Setup the integration + +If you don't have cert-manager configured yet, follow these steps: - + + +Virtual Cluster Create the `ClusterIssuer`. - Create the Issuer +:::tip +This should create a corresponding Issuer in the host cluster. +::: -Create a named `issuer.yaml` with the following content: +Create a file named `issuer.yaml`: -```yaml title="ClusterIssuer configuration" +```yaml title="Create ClusterIssuer" +cat < issuer.yaml apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: @@ -50,48 +88,41 @@ metadata: spec: acme: # highlight-start - # Replace this email address with your own. + # Replace this email address with your own # Let's Encrypt will use this to contact you about expiring - # certificates, and issues related to your account. + # certificates, and issues related to your account # highlight-end email: user@example.com server: https://acme-staging-v02.api.letsencrypt.org/directory privateKeySecretRef: - # Secret resource that will be used to store the account's private key. name: example-issuer-account-key - # Add a single challenge solver, HTTP01 using nginx solvers: - http01: ingress: ingressClassName: nginx +EOF ``` - - -Apply the Issuer configuration: +Apply to the host cluster: -```bash title="Apply the Issuer configuration" -kubectl apply -f issuer.yaml +```bash title="Apply ClusterIssuer to host cluster" +kubectl --context=$HOST_CTX apply -f issuer.yaml ``` -:::note -This creates a corresponding Issuer in the host cluster. -::: - - -Create and apply Issuer and Certificate -After the virtual cluster is running, create an Issuer and Certificate inside the virtual cluster. This guide uses a `letsencrypt-staging` issuer for demonstration purposes. +## Create a certificate - +With the `ClusterIssuers` configured, create a certificate within the virtual cluster. -Create the Certificate -Create a file named `certificate.yaml` with the following content: +Virtual Cluster Create the Certificate -```yaml title="Certificate configuration" +Create a file named `certificate.yaml`: + +```yaml title="Create Certificate" +cat < certificate.yaml apiVersion: cert-manager.io/v1 kind: Certificate metadata: @@ -108,55 +139,50 @@ spec: usages: - digital signature - key encipherment +EOF ``` - - -Apply the Certificate configuration: -```bash title="Apply the Certificate configuration" -kubectl apply -f certificate.yaml +```bash title="Apply Certificate in virtual cluster" +kubectl --context=$VCLUSTER_CTX apply -f certificate.yaml ``` :::tip -After the certificate is created in the virtual cluster, the integration syncs the created secret back to the virtual cluster after the cert-manager operator creates it in the host cluster. +Once that certificate is created in the virtual cluster, the integration syncs the created secret back to the virtual cluster after the cert-manager operator creates it in the host cluster, and the certificate is ready to use. ::: - -## Verify the integration +## Verify the setup + + + +Host Cluster Check the `ClusterIssuer` - - -Check the status of the Issuer: +```bash title="Check ClusterIssuer in host cluster" +kubectl --context=$HOST_CTX describe clusterissuer letsencrypt-staging +``` - ```bash title="Check Issuer status" - kubectl describe clusterissuer letsencrypt-staging - ``` - + + - -Check the status of the Certificate: +Virtual Cluster Check resources - ```bash title="Check Certificate status" - kubectl describe certificate quickstart-example-tls - ``` - - -Verify that the secret containing the certificate has been created: +```bash title="Check Issuer and Certificate in virtual cluster" +kubectl --context=$VCLUSTER_CTX describe issuer letsencrypt-staging -n default - ```bash title="Verify secret creation" - kubectl get secret quickstart-example-tls - ``` - - +kubectl --context=$VCLUSTER_CTX describe certificate quickstart-example-tls -n default + +kubectl --context=$VCLUSTER_CTX get secret quickstart-example-tls -n default +``` + + -## Using the certificate in an application +## Using the certificate -To use the created certificate in an application, reference the secret in your Ingress resource: +To use your certificate in an application, reference it in your Ingress resource: -```yaml title="Example Ingress using the certificate" +```yaml title="ingress.yaml" apiVersion: networking.k8s.io/v1 kind: Ingress metadata: @@ -165,32 +191,38 @@ metadata: kubernetes.io/ingress.class: nginx spec: tls: - - hosts: - - example.example.com - secretName: quickstart-example-tls + - hosts: + - example.example.com + secretName: quickstart-example-tls rules: - - host: example.example.com - http: - paths: - - path: / - pathType: Prefix - backend: - service: - name: example-service - port: - number: 80 + - host: example.example.com + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: example-service + port: + number: 80 ``` ## Troubleshooting -If you encounter issues with the cert-manager integration, consider the following: +Host Cluster +- Verify cert-manager is running + +```bash title="Verify Cert Manager Installation +kubectl --context=$HOST_CTX -n cert-manager get pods +``` +- Check cert-manager logs for errors - Ensure proper RBAC permissions are configured -- Ensure that cert-manager is properly installed and running in the host cluster. -- Check the cert-manager logs in the host cluster for any error messages. -- Verify that the Issuer and Certificate resources are correctly configured. -- Ensure that the virtual cluster has the necessary permissions to create and manage certificates. +Virtual Cluster +- Verify the integration is enabled in your vcluster configuration +- Check that secrets are syncing correctly between clusters +- Ensure your Issuer and Certificate configurations are correct -For more detailed troubleshooting, refer to the [cert-manager troubleshooting guide](https://cert-manager.io/docs/troubleshooting/). +For detailed troubleshooting steps, see the [cert-manager troubleshooting guide](https://cert-manager.io/docs/troubleshooting/). ## Config reference