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

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
```
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
```
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
```
Note: It may take up to 10-20 minutes for the load balancer to begin functioning.
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.
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.
Note: You must wait for the DNS records you configured in the previous step to propagate before continuing.

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
(...)
```
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:

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

Using the gcloud command-line tool:

gcloud compute addresses delete [ADDRESS_NAME] --global

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

Console

Go to the External IP addresses page in the GCP Console.
Go to the External IP addresses page
Check the box next to the IP address to release.
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

Learn more about on HTTP(S) load balancers on Google Cloud Platform.
Learn how to use self-managed SSL certificates on Google Kubernetes Engine.

Esta página foi útil? Conte sua opinião sobre:

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Última atualização: Abril 9, 2019.

Using Google-managed SSL certificates

Overview

Creating an Ingress with a managed certificate

Limitations

Prerequisites

gcloud

Console

Setting up the managed certificate

Migrating to Google-managed certificates from self-managed certificates

Removing a managed certificate

gcloud

Console

Troubleshooting

spec.domains in body should have at most 1 items

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]\.?$'

spec.domains in body should be at most 63 chars long

What's next

Enviar comentários sobre…

`spec.domains in body should have at most 1 items`

`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]\.?$'`

`spec.domains in body should be at most 63 chars long`