Using Google-managed SSL certificates

Overview

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-certificates to the Ingress. This annotation is a comma-separated list of ManagedCertificate resources, cert1,cert2,cert3 for example.

The ManagedCertificate resource must be created in the same namespace as the Ingress.

Limitations

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.

Prerequisites

  • 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 gcloud command-line tool or the GCP Console to create a reserved IP address, named example-ip-address:

    gcloud

    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
    ...
    

    Console

    1. Go to the Reserve a static address page in the GCP Console.

      Go to the Reserve a static address page

    2. Specify a name for this IP address, example-ip-address.
    3. Specify whether this is an IPv4 or IPv6 address. The following example uses an IPv4 address.
    4. Select the Global option for the address type.
    5. Click Reserve to reserve the IP.
    6. The IP address will be listed in the External Address column.

Setting up the managed certificate

  1. Create a ManagedCertificate resource. This resource specifies the domain that the SSL certificate will be created for. Wildcard domains are not supported. The spec.domains list must contain only one domain.

    Save the following example ManagedCertificate manifest to a filed named example-certificate.yaml. Replace example.com with your domain name:

    apiVersion: networking.gke.io/v1beta1
    kind: ManagedCertificate
    metadata:
      name: example-certificate
    spec:
      domains:
        - example.com
    

    Use kubectl to create the resource:

    kubectl apply -f example-certificate.yaml
    
  2. Create a NodePort Service to expose your application to the Internet. The following is an example Service manifest file, example-service.yaml.

    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.

    Use kubectl to create the Service:

    kubectl apply -f example-service.yaml
    
  3. Create an Ingress, linking it to the ManagedCertificate you created previously.

    • Set the networking.gke.io/managed-certificates annotation to the name of your certificate.
    • For the spec.backend.serviceName field, use the name of the service you created in the previous step.
    • Set the spec.backend.servicePort field to the port you specified in your Service manifest.
    • Set the kubernetes.io/ingress.global-static-ip-name annotation to the name of your reserved IP address.

    The following is an example Ingress manifest, example-ingress.yaml:

    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
    

    Use kubectl to create the Ingress:

    kubectl apply -f example-ingress.yaml
    
  4. 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 ADDRESS column, 203.0.113.32 in 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.

  5. 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.

  6. 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.CertificateStatus field will be Active. The following example shows the output of kubectl describe after 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
    (...)
    
  7. 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.

  1. Add a new managed certificate to the Ingress, as described in the Setting up the managed certificate section.
  2. Wait until the status of the Google-managed certificate resource is Active. Check the status of the certificate with kubectl describe managedcertificate.
  3. 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.

  1. Delete the ManagedCertificate resource with kubectl:

    kubectl delete -f example-certificate.yaml
    

    You will get the following output:

    managedcertificate.networking.gke.io "example-certificate" deleted
    
  2. 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.

  3. Release the static IP address that you reserved for your load balancer:

gcloud

Using the gcloud command-line tool:

gcloud compute addresses delete [ADDRESS_NAME] --global

where [ADDRESS_NAME] is the name of the IP address.

Console

  1. Go to the External IP addresses page in the GCP Console.

    Go to the External IP addresses page

  2. Check the box next to the IP address to release.
  3. Click Release IP address.

Troubleshooting

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 *.example.com

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.

What's next

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Kubernetes Engine Documentation