Set up a custom domain for a workload

This tutorial shows how to set up a custom domain and prepare a certificate required for exposing a workload. It uses Gardener External DNS Management and Certificate Management components.

NOTE: Skip this tutorial if you use a Kyma domain instead of your custom domain.

Prerequisites

Deploy a sample HttpBin service and a sample Function.
If you use a cluster not managed by Gardener, install the External DNS Management and Certificate Management components manually in a dedicated Namespace.

Steps

Create a Secret containing credentials for the DNS cloud service provider account in your Namespace.
- Choose your DNS cloud service provider and create a secret in your Namespace. To learn how to do it, follow the guidelines provided in the External DNS Management documentation.
- Export the name of the created Secret as an environment variable:
  Click to copy
```
export SECRET={SECRET_NAME}
```

Create a DNSProvider custom resource (CR).

Export the following values as environment variables.
NOTE: As the SPEC_TYPE, use the relevant provider type. The DOMAIN_NAME value specifies the name of a domain that you own, for example, mydomain.com.
Click to copy
```
export SPEC_TYPE={PROVIDER_TYPE}
export DOMAIN_TO_EXPOSE_WORKLOADS={DOMAIN_NAME} 
```

To create a DNSProvider CR, run:

Click to copy

cat <<EOF | kubectl apply -f -
apiVersion: dns.gardener.cloud/v1alpha1
kind: DNSProvider
metadata:
  name: dns-provider
  namespace: $NAMESPACE
  annotations:
    dns.gardener.cloud/class: garden
spec:
  type: $SPEC_TYPE
  secretRef:
    name: $SECRET
  domains:
    include:
      - $DOMAIN_TO_EXPOSE_WORKLOADS
EOF

Create a DNSEntry CR.

Export the following values as environment variables:
Click to copy
```
export IP=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}') # Assuming only one LoadBalancer with external IP
```
NOTE: For some cluster providers you need to replace the ip with the hostname, for example, in AWS, set jsonpath='{.status.loadBalancer.ingress[0].hostname}'.

To create a DNSEntry CR, run:

Click to copy

cat <<EOF | kubectl apply -f -
apiVersion: dns.gardener.cloud/v1alpha1
kind: DNSEntry
metadata:
  name: dns-entry
  namespace: $NAMESPACE
  annotations:
    dns.gardener.cloud/class: garden
spec:
  dnsName: "*.$DOMAIN_TO_EXPOSE_WORKLOADS"
  ttl: 600
  targets:
    - $IP
EOF

Create an Issuer CR.

Export the following values as environment variables:
Click to copy
```
export EMAIL={YOUR_EMAIL_ADDRESS}
```

To create an Issuer CR, run:

Click to copy

cat <<EOF | kubectl apply -f -
apiVersion: cert.gardener.cloud/v1alpha1
kind: Issuer
metadata:
  name: letsencrypt-staging
  namespace: $NAMESPACE
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: $EMAIL
    autoRegistration: true
    privateKeySecretRef:
      name: letsencrypt-staging-secret
      namespace: $NAMESPACE
    domains:
      include:
        - $DOMAIN_TO_EXPOSE_WORKLOADS
        - "*.$DOMAIN_TO_EXPOSE_WORKLOADS"
EOF

Create a Certificate CR.
- Export the following values as environment variables:
  NOTE: The TLS_SECRET is the name of the TLS Secret, for example httpbin-tls-credentials. The ISSUER value is the name of the Issuer CR, for example, letsencrypt-staging.
  Click to copy
```
export TLS_SECRET={TLS_SECRET_NAME}
export ISSUER={ISSUER_NAME}
```
- To create a Certificate CR, run:
  Click to copy
```
cat <<EOF | kubectl apply -f -
apiVersion: cert.gardener.cloud/v1alpha1
kind: Certificate
metadata:
  name: httpbin-cert
  namespace: istio-system
spec:  
  secretName: $TLS_SECRET
  commonName: $DOMAIN_TO_EXPOSE_WORKLOADS
  issuerRef:
    name: $ISSUER
    namespace: $NAMESPACE
EOF
```
  NOTE: While using the default configuration, certificates with the Let's Encrypt issuer are valid for 90 days and automatically renewed 60 days before their validity expires. Use the --issuer.renewal-window command line parameter to adjust the time window between the renewal and the expiration of a certificate. For more information on Gardener Certificate Management, read the Gardener documentation.
- To check the certificate status, run:
  Click to copy
```
kubectl get certificate httpbin-cert -n istio-system
```
Follow this tutorial to set up a TLS Gateway.

Visit the Gardener external DNS management documentation to see more examples of custom resources for services and ingresses.