In Google Kubernetes Engine, you can use Ingresses to create HTTPS load balancers with automatically configured SSL certificates. Google-managed SSL certificates are provisioned, renewed, and managed for your domain names. Read more about Google-managed SSL certificates here.
Creating an Ingress with a managed certificate
To configure a managed SSL certificate and associate it with an Ingress, you need to:
- Create a ManagedCertificate object.
- Associate the ManagedCertificate object to an Ingress by adding an annotation
networking.gke.io/managed-certificatesto the Ingress. This annotation is a comma-separated list of ManagedCertificate resources,
The ManagedCertificate resource must be created in the same namespace as the Ingress.
Google-managed certificates are less flexible than certificates you obtain and manage yourself. Managed certificates support a single, non-wildcard domain. Self-managed certificates can support wildcards and multiple subject alternative names (SANs).
If you require self-managed certificates or if you already own SSL certificates that you would like to configure on your Ingress, refer to the Ingress documentation.
The number and type of certificates supported by an Ingress are defined by the limits of GCP managed SSL certificates.
- You must own the domain name. The domain name must be no longer than 63 characters. You can use Google Domains or another registrar.
Create a reserved (static) external IP address. Reserving a static IP address guarantees that it will remain yours, even if you delete the Ingress. If you do not reserve an address it may change requiring you to reconfigure your domain's DNS records. Use
gcloudcommand-line tool or the GCP Console to create a reserved IP address, named
gcloud compute addresses create example-ip-address --global
To find the static IP address you created:
$ gcloud compute addresses describe example-ip-address --global address: 203.0.113.32 ...
- Go to the Reserve a static address page in the GCP Console.
- Specify a name for this IP address,
- Specify whether this is an
IPv6address. The following example uses an
- Select the Global option for the address type.
- Click Reserve to reserve the IP.
- The IP address will be listed in the External Address column.
Setting up the managed certificate
Create a ManagedCertificate resource. This resource specifies the domain that the SSL certificate will be created for. Wildcard domains are not supported. The
spec.domainslist must contain only one domain.
Save the following example ManagedCertificate manifest to a filed named
example.comwith your domain name:
apiVersion: networking.gke.io/v1beta1 kind: ManagedCertificate metadata: name: example-certificate spec: domains: - example.com
kubectlto create the resource:
kubectl apply -f example-certificate.yaml
Create a NodePort Service to expose your application to the Internet. The following is an example Service manifest file,
apiVersion: v1 kind: Service metadata: name: example-nodeport-service spec: type: NodePort ports: - protocol: TCP port: 80 targetPort: 8080
This example specification doesn't select any Pods to include in the Service. This is sufficient to demonstrate how to configure Managed Certificates. In practical use though, a Service specifcation should include a selector.
Refer to the NodePort documentation for details on how to configure the Service.
kubectlto create the Service:
kubectl apply -f example-service.yaml
Create an Ingress, linking it to the ManagedCertificate you created previously.
- Set the
networking.gke.io/managed-certificatesannotation to the name of your certificate.
- For the
spec.backend.serviceNamefield, use the name of the service you created in the previous step.
- Set the
spec.backend.servicePortfield to the port you specified in your Service manifest.
- Set the
kubernetes.io/ingress.global-static-ip-nameannotation to the name of your reserved IP address.
The following is an example Ingress manifest,
apiVersion: extensions/v1beta1 kind: Ingress metadata: name: example-ingress annotations: kubernetes.io/ingress.global-static-ip-name: example-ip-address networking.gke.io/managed-certificates: example-certificate spec: backend: serviceName: example-nodeport-service servicePort: 80
kubectlto create the Ingress:
kubectl apply -f example-ingress.yaml
- Set the
Look up the IP address of the load balancer created in the previous step. Use the following command to get the IP address of the load balancer:
$ kubectl get ingress NAME HOSTS ADDRESS PORTS AGE example-ingress * 203.0.113.32 80 54s
The load balancer's IP address is listed in the
203.0.113.32in this example. If you are using a reserved static IP address that will be the load balancer's address.
If the address is not listed, wait for the Ingress to finish setting up.
Configure the DNS records for your domain to point to the IP address of the load balancer. If you use Cloud DNS, you can refer to the Managing Records guide for details.
Wait for the managed certificate to be provisioned. This may take up to 15 minutes. You can check on the status of the certificate with the following command:
kubectl describe managedcertificate
Once a certificate is successfully provisioned, the value of the
Status.CertificateStatusfield will be
Active. The following example shows the output of
kubectl describeafter the example certificate is successfully provisioned:
Name: example-certificate Namespace: default Labels:
Annotations: API Version: networking.gke.io/v1beta1 Kind: ManagedCertificate (...) Spec: Domains: example.com Status: CertificateStatus: Active (...)
Verify that SSL is working by visiting your domain using the
https://prefix. Your browser will indicate that the connection is secure and you can view the certificate details.
Migrating to Google-managed certificates from self-managed certificates
When you migrate an Ingress from using self-managed SSL certificates to Google-managed SSL certificates, do not delete any self-managed SSL certificates before the Google-managed SSL certificates are active. After the Google-managed SSL certificates are successfully provisioned, they automatically become active. When the Google-managed SSL certificates are active, you can delete your self-managed SSL certificates.
Use these instructions for migrating from self-managed to Google-managed SSL certificates.
- Add a new managed certificate to the Ingress, as described in the Setting up the managed certificate section.
- Wait until the status of the Google-managed certificate resource is Active.
Check the status of the certificate with
kubectl describe managedcertificate.
- When the status is Active, update the Ingress to remove the references to the self-managed certificate.
Removing a managed certificate
To remove a managed certificate from your cluster you must delete the ManagedCertificate resource and remove the Ingress annotation that references it.
Delete the ManagedCertificate resource with
kubectl delete -f example-certificate.yaml
You will get the following output:
managedcertificate.networking.gke.io "example-certificate" deleted
Remove the annotation from the Ingress:
kubectl annotate ingress example-ingress networking.gke.io/managed-certificates-
Notice the minus sign, "-", at the end of the command.
Release the static IP address that you reserved for your load balancer:
gcloud command-line tool:
gcloud compute addresses delete [ADDRESS_NAME] --global
[ADDRESS_NAME] is the name of the IP address.
- Go to the External IP addresses page in the GCP Console.
- Check the box next to the IP address to release.
- Click Release IP address.
ManagedCertificate definitions are validated before the ManagedCertificate resource is created. If validation fails the ManagedCertificate resource is not created and an error message is printed. The different failure reasons are explained below:
spec.domains in body should have at most 1 items
Your ManagedCertificate manifests lists more than one domain in the
spec.domains field. Managed certificates support only one domain.
spec.domains in body should match '^(([a-zA-Z0-9]+|[a-zA-Z0-9][-a-zA-Z0-9]*[a-zA-Z0-9])\.)+[a-zA-Z][-a-zA-Z0-9]*[a-zA-Z0-9]\.?$'
You specified an invalid domain name or a wildcard domain name in the
spec.domains field. Managed certificates don't support wildcard domains like
spec.domains in body should be at most 63 chars long
You specified a domain name that is too long. Managed certificates support domain names with at most 63 characters.