Skip to content

Commit

Permalink
chore: address PR feedback
Browse files Browse the repository at this point in the history 
- address feedback
- improve usability and commands flow

Signed-off-by: Piotr Zaniewski <[email protected]>
  • Loading branch information
@Piotr1215
Piotr1215 committed Dec 17, 2024
1 parent c16c1b9 commit 358e079
Showing 1 changed file with 122 additions and 90 deletions.
212 changes: 122 additions & 90 deletions vcluster/_fragments/integrations/cert-manager.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,97 +1,128 @@
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';
<ProAdmonition />

import Deploy from '../../_partials/deploy/deploy.mdx'
# Cert manager integration

import ProAdmonition from '../../_partials/admonitions/pro-admonition.mdx'

<ProAdmonition/>
This guide shows how to set up cert-manager integration with your virtual cluster.

### Prerequisites

<BasePrerequisites />

- `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:
<!-- TODO:(piotr1215) add link to cert-manager integration when available -->

Enable the cert-manager integration in your virtual cluster configuration:

```yaml title="Enable cert-manager integration"
integrations:
certManager:
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:

<Flow id="cert-manager-integration">
<Step>
<Step>

<Highlight color="green">Virtual Cluster</Highlight> Create the `ClusterIssuer`.

Create the Issuer
:::tip
This should create a corresponding Issuer in the host cluster.
:::

Create a <Label>file</Label> named `issuer.yaml` with the following content:
Create a file named `issuer.yaml`:

```yaml title="ClusterIssuer configuration"
```yaml title="Create ClusterIssuer"
cat <<EOF > issuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-staging
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: [email protected]
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
```

</Step>
<Step>
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.
:::

</Step>
<Step>

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

</Step>
With the `ClusterIssuers` configured, create a certificate within the virtual cluster.

<Step>
Create the Certificate

Create a file named `certificate.yaml` with the following content:
<Highlight color="green">Virtual Cluster</Highlight> Create the Certificate

```yaml title="Certificate configuration"
Create a file named `certificate.yaml`:

```yaml title="Create Certificate"
cat <<EOF > certificate.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
Expand All @@ -108,55 +139,50 @@ spec:
usages:
- digital signature
- key encipherment
EOF
```
</Step>
<Step>
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.
:::

</Step>
</Flow>

## Verify the integration
## Verify the setup

<Step>

<Highlight>Host Cluster</Highlight> Check the `ClusterIssuer`

<Flow id="verify-integration">
<Step>
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
```
</Step>
</Step>
<Step>

<Step>
Check the status of the Certificate:
<Highlight color="green">Virtual Cluster</Highlight> Check resources

```bash title="Check Certificate status"
kubectl describe certificate quickstart-example-tls
```
</Step>
<Step>
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
```
</Step>
</Flow>
kubectl --context=$VCLUSTER_CTX describe certificate quickstart-example-tls -n default

kubectl --context=$VCLUSTER_CTX get secret quickstart-example-tls -n default
```

</Step>
</Flow>

## 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:
Expand All @@ -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:
<Highlight>Host Cluster</Highlight>
- 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.
<Highlight color="green">Virtual Cluster</Highlight>
- 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

Expand Down

0 comments on commit 358e079

Please sign in to comment.