Kubernetes Ingress with Cert-Manager

This example demonstrates the use of Istio as a secure Kubernetes Ingress controller with TLS certificates issued by Let’s Encrypt.

You will start with a clean Istio installation, create an example service, expose it using the Kubernetes Ingress resource and get it secured by instructing cert-manager (bundled with Istio) to manage issuance and renewal of TLS certificates that will be further delivered to the Istio ingress gateway and hot-swapped as necessary via the means of Secrets Discovery Service (SDS).

Before you begin

  • Install Istio making sure to enable ingress gateway with Kubernetes Ingress support, SDS. Here’s an example of how to do it:
  1. $ istioctl manifest apply \
  2. --set values.gateways.istio-ingressgateway.sds.enabled=true \
  3. --set values.global.k8sIngress.enabled=true \
  4. --set values.global.k8sIngress.enableHttps=true \
  5. --set values.global.k8sIngress.gatewayName=ingressgateway

By default istio-ingressgateway will be exposed as a LoadBalancer service type. You may want to change that by setting the gateways.istio-ingressgateway.type installation option to NodePort if this is more applicable to your Kubernetes environment.

Configuring DNS name and gateway

Take a note of the external IP address of the istio-ingressgateway service:

  1. $ kubectl -n istio-system get service istio-ingressgateway

Configure your DNS zone so that the domain you’d like to use for this example is resolving to the external IP address of istio-ingressgateway service that you’ve captured in the previous step. You will need a real domain name for this example in order to get a TLS certificate issued. Let’s store the configured domain name into an environment variable for further use:

  1. $ INGRESS_DOMAIN=mysubdomain.mydomain.edu

Your Istio installation contains an automatically generated gateway resource configured to serve the routes defined by the Kubernetes Ingress resources. By default it does not use SDS, so you need to modify it in order to enable the delivery of the TLS certificates to the istio-ingressgateway via SDS:

  1. $ kubectl -n istio-system edit gateway

…and modify the tls section corresponding to the https-default port as follows:

  1. $ kubectl -n istio-system \
  2. patch gateway istio-autogenerated-k8s-ingress --type=json \
  3. -p='[{"op": "replace", "path": "/spec/servers/1/tls", "value": {"credentialName": "ingress-cert", "mode": "SIMPLE", "privateKey": "sds", "serverCertificate": "sds"}}]'

Now it’s time to setup a demo application.

Setting up a demo application

You will be using a simple helloworld application for this example. The following command will spin up the Deployment and Service for the demo application and expose the service using an Ingress resource that will be handled by istio-ingressgateway.

  1. $ cat <<EOF | kubectl apply -f -
  2. apiVersion: v1
  3. kind: Service
  4. metadata:
  5. name: helloworld
  6. labels:
  7. app: helloworld
  8. spec:
  9. ports:
  10. - port: 5000
  11. name: http
  12. selector:
  13. app: helloworld
  14. ---
  15. apiVersion: apps/v1
  16. kind: Deployment
  17. metadata:
  18. name: helloworld
  19. spec:
  20. selector:
  21. matchLabels:
  22. app: helloworld
  23. template:
  24. metadata:
  25. labels:
  26. app: helloworld
  27. spec:
  28. containers:
  29. - name: helloworld
  30. image: istio/examples-helloworld-v1
  31. resources:
  32. requests:
  33. cpu: "100m"
  34. imagePullPolicy: IfNotPresent
  35. ports:
  36. - containerPort: 5000
  37. ---
  38. apiVersion: extensions/v1beta1
  39. kind: Ingress
  40. metadata:
  41. annotations:
  42. kubernetes.io/ingress.class: istio
  43. name: helloworld-ingress
  44. spec:
  45. rules:
  46. - host: "$INGRESS_DOMAIN"
  47. http:
  48. paths:
  49. - path: /hello
  50. backend:
  51. serviceName: helloworld
  52. servicePort: 5000
  53. ---
  54. EOF

Notice use of the INGRESS_DOMAIN variable you defined earlier

Now you should be able to access your demo application via HTTP:

  1. $ curl http://$INGRESS_DOMAIN/hello
  2. Hello version: v1, instance: helloworld-5d498979b6-jp2mf

HTTPS access still won’t work as you don’t have any TLS certificates. Let’s fix that.

Getting a Let’s Encrypt certificate issued using cert-manager

At this point your Istio installation should have cert-manager up and running with two ClusterIssuer resources configured (for production and staging ACME-endpoints provided by Let’s Encrypt). You will be using staging endpoint for this example (feel free to try swapping letsencrypt-staging for letsencrypt to get a browser-trusted certificate issued).

In order to have a certificate issued and managed by cert-manager you need to create a Certificate resource:

  1. $ cat <<EOF | kubectl apply -f -
  2. apiVersion: certmanager.k8s.io/v1alpha1
  3. kind: Certificate
  4. metadata:
  5. name: ingress-cert
  6. namespace: istio-system
  7. spec:
  8. secretName: ingress-cert
  9. issuerRef:
  10. name: letsencrypt-staging
  11. kind: ClusterIssuer
  12. commonName: $INGRESS_DOMAIN
  13. dnsNames:
  14. - $INGRESS_DOMAIN
  15. acme:
  16. config:
  17. - http01:
  18. ingressClass: istio
  19. domains:
  20. - $INGRESS_DOMAIN
  21. ---
  22. EOF

Notice that the secretName matches the credentialName attribute value that you previously used while configuring the gateway resource. The Certificate resource will be processed by cert-manager and a new certificate will eventually be issued. Consult the status of the Certificate resource to check the progress:

  1. $ kubectl -n istio-system describe certificate ingress-cert
  2. -> status should eventually flip to 'Certificate issued successfully'

At this point the service should become available over HTTPS as well:

  1. $ curl --insecure https://$INGRESS_DOMAIN/hello
  2. Hello version: v1, instance: helloworld-5d498979b6-jp2mf

Note that you have to use the —insecure flag as certificates issued by the “staging” ACME-endpoints aren’t trusted.

Moving to production from staging

Now to switch to the production letsencrypt issuer. First we’ll reapply the certificate.

  1. $ cat <<EOF | kubectl apply -f -
  2. apiVersion: certmanager.k8s.io/v1alpha1
  3. kind: Certificate
  4. metadata:
  5. name: ingress-cert
  6. namespace: istio-system
  7. spec:
  8. secretName: ingress-cert
  9. issuerRef:
  10. name: letsencrypt
  11. kind: ClusterIssuer
  12. commonName: $INGRESS_DOMAIN
  13. dnsNames:
  14. - $INGRESS_DOMAIN
  15. acme:
  16. config:
  17. - http01:
  18. ingressClass: istio
  19. domains:
  20. - $INGRESS_DOMAIN
  21. ---
  22. EOF
  1. certificate.certmanager.k8s.io/ingress-cert configured

Now delete the secret to force cert-manager to request a new certificate from the production issuer:

  1. $ kubectl delete secret -n istio-system ingress-cert

And watch that cert for a successful issuance:

  1. $ watch -n1 kubectl describe cert ingress-cert -n istio-system

you should see something like:

  1. Normal CertIssued 13m cert-manager Certificate issued successfully

See also

Istio as a Proxy for External Services

Configure Istio ingress gateway to act as a proxy for external services.

Ingress Gateway without TLS Termination

Describes how to configure SNI passthrough for an ingress gateway.

Deploy a Custom Ingress Gateway Using Cert-Manager

Describes how to deploy a custom ingress gateway using cert-manager manually.

Configuring Istio Ingress with AWS NLB

Describes how to configure Istio ingress with a network load balancer on AWS.

Consuming External Web Services

Describes a simple scenario based on Istio's Bookinfo example.

Ingress Gateways

Describes how to configure an Istio gateway to expose a service outside of the service mesh.