This page shows how you can use Ingress objects to create external load balancers with Google-managed SSL certificates. These certificates are Domain Validation (DV) certificates that Google provisions, renews, and manages for your domain names. These certificates don't demonstrate your individual or organizational identity.
This page is for Networking specialists and Security specialists who plan and implement network security and develop and maintain security policies. To learn more about common roles and example tasks that we reference in Google Cloud content, see Common GKE Enterprise user roles and tasks.
To learn how to create Google-managed certificates with Google Cloud, see Google-managed certificates.
GKE Google-managed SSL certificates support public and private clusters.
Creating an Ingress with a Google-managed certificate
To configure a Google-managed SSL certificate and associate it with an Ingress, you need to:
- Create a
ManagedCertificate
object in the same namespace as the Ingress. - Associate the
ManagedCertificate
object to an Ingress by adding thenetworking.gke.io/managed-certificates
annotation to the Ingress. This annotation is a comma-separated list ofManagedCertificate
objects.
Limitations
Google-managed certificates are less flexible than certificates you obtain and manage yourself. Google-managed certificates support up to 100 non-wildcard domains. Unlike self-managed certificates, Google-managed certificates don't support wildcard domains.
If you require self-managed certificates or if you already own SSL certificates that you would like to configure on your Ingress, see Setting up HTTPS (TLS) between client and load balancer.
The number and type of certificates supported by an Ingress are defined by the limits of Google-managed SSL certificates.
Updates on Google-managed certificates are not supported. For more information, see Manually updating a Google-managed certificate.
If the certificate is revoked directly with the Certificate Authority, Google does not automatically rotate the certificate. You must delete the ManagedCertificate and create a new one.
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.
- If you use a GKE Standard cluster, the
HttpLoadBalancing
add-on must be enabled. - Your
ingressClassName
must be"gce"
. - You must apply
Ingress
andManagedCertificate
resources in the same project and namespace. Create a reserved (static) external IP address. Reserving a static IP address ensures that it remains yours, even if you delete the Ingress. If you don't reserve an IP address, it might change, requiring you to reconfigure your domain's DNS records. Use Google Cloud CLI or the Google Cloud console to create a reserved IP address.
gcloud
To create a reserved IP address, run the following command:
gcloud compute addresses create ADDRESS_NAME --global
Replace
ADDRESS_NAME
with the name of the reserved IP address you are creating.To find the static IP address you created, run the following command:
gcloud compute addresses describe ADDRESS_NAME --global
The output is similar to the following:
address: 203.0.113.32 ...
Console
To create a reserved IP address, perform the following steps:
Go to the External IP addresses page in the Google Cloud console.
Specify a name for the IP address (for example,
example-ip-address
).Specify if you want an IPv4 or IPv6 address.
Select the Global option for Type.
Click Reserve. The IP address is listed in the External Address column.
Config Connector
Note: This step requires Config Connector. Follow the installation instructions to install Config Connector on your cluster.
To deploy this manifest, download it to your machine ascompute-address.yaml
, and run:kubectl apply -f compute-address.yaml
Setting up a Google-managed certificate
Create a
ManagedCertificate
object. This resource specifies the domains for the SSL certificate. Wildcard domains are not supported.The following manifest describes a
ManagedCertificate
object. Save the manifest asmanaged-cert.yaml
.apiVersion: networking.gke.io/v1 kind: ManagedCertificate metadata: name: managed-cert spec: domains: - FQDN_1 - FQDN_2
Replace the following:
FQDN_1
,FQDN_2
: Fully-qualified domain names that you own. For example,example.com
andwww.example.com
.
Apply the manifest to your cluster:
kubectl apply -f managed-cert.yaml
Create a Service of type
NodePort
to expose your application to the internet.The following manifest describes a Service of type
NodePort
. Save the manifest asmc-service.yaml
.apiVersion: v1 kind: Service metadata: name: mc-service spec: selector: app: mc-service type: NodePort ports: - protocol: TCP port: 80 targetPort: 8080
Apply the manifest to your cluster:
kubectl apply -f mc-service.yaml
Create an Ingress.
The following manifest describes an Ingress that uses the
ManagedCertificate
you created. Save the manifest asmanaged-cert-ingress.yaml
.apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: managed-cert-ingress annotations: kubernetes.io/ingress.global-static-ip-name: ADDRESS_NAME networking.gke.io/managed-certificates: managed-cert kubernetes.io/ingress.class: "gce" # Updated annotation spec: defaultBackend: service: name: mc-service port: number: SERVICE_PORT
Replace the following:
ADDRESS_NAME
: the name of your reserved IP address.SERVICE_PORT
: the value ofports.port
in your Service manifest.
Apply the manifest to your cluster:
kubectl apply -f managed-cert-ingress.yaml
Get the IP address of the load balancer:
kubectl get ingress
The output is similar to the following:
NAME HOSTS ADDRESS PORTS AGE managed-cert-ingress * 203.0.113.32 80 54s
The load balancer's IP address is listed in the
ADDRESS
column. 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 domains to point to the IP address of the load balancer. If you use Cloud DNS, see Managing records for details.
Wait for the Google-managed certificate to finish provisioning. This might take up to 60 minutes. You can check the status of the certificate using the following command:
kubectl describe managedcertificate managed-cert
The output is similar to the following:
Name: managed-cert Namespace: default Labels: <none> Annotations: <none> API Version: networking.gke.io/v1 Kind: ManagedCertificate (...) Spec: Domains: FQDN_1 FQDN_2 Status: CertificateStatus: Active (...)
The value of the
Status.CertificateStatus
field indicates the certificate is provisioned. IfStatus.CertificateStatus
is notActive
, the certificate is not yet provisioned.You can check the events on an Ingress by using the following command:
kubectl describe ingress INGRESS_NAME
Replace
INGRESS_NAME
with the name of your Ingress.Verify that SSL is working by visiting your domains using the
https://
prefix. Your browser indicates 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, don't 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 Google-managed certificate to the Ingress, as described in the Setting up a Google-managed certificate section.
Wait until the status of the Google-managed certificate resource is Active. Check the status of the certificate with the following command:
kubectl describe managedcertificate managed-cert
When the status is
Active
, update the Ingress to remove the references to the self-managed certificate.
Removing a Google-managed certificate
To remove a Google-managed certificate from your cluster you must delete the
ManagedCertificate
object and remove the Ingress annotation that references
it.
Delete the
ManagedCertificate
object:kubectl delete -f managed-cert.yaml
The output is similar to the following:
managedcertificate.networking.gke.io "managed-cert" deleted
Remove the annotation from the Ingress:
kubectl annotate ingress managed-cert-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.
You can use the Google Cloud CLI, the Google Cloud console, or Config Connector to release a reserved IP address.
gcloud
Use the following command to release the reserved IP address:
gcloud compute addresses delete ADDRESS_NAME --global
Replace
ADDRESS_NAME
with the name of the IP address.Console
To release the reserved IP address, perform the following steps:
Go to the External IP addresses page in the Google Cloud console.
Select the checkbox next to the IP address you want to release.
Click Release IP address.
Config Connector
Note: This step requires Config Connector. Follow the installation instructions to install Config Connector on your cluster.
To deploy this manifest, download it to your machine as
compute-address.yaml
, and run:kubectl delete -f compute-address.yaml
Troubleshooting
This section provides information on how to resolve issues with Google-managed certificates.
Check events on ManagedCertificate
and Ingress resources
If you exceed the number of allowed certificates, an event with a
TooManyCertificates
reason is added to the ManagedCertificate
. You can
check the events on a ManagedCertificate
object using the following command:
kubectl describe managedcertificate CERTIFICATE_NAME
Replace CERTIFICATE_NAME
with the name of your
ManagedCertificate
.
If you attach a non-existent ManagedCertificate
to an Ingress, an event
with a MissingCertificate
reason is added to the Ingress. You can check the
events on an Ingress by using the following command:
kubectl describe ingress INGRESS_NAME
Replace INGRESS_NAME
with the name of your Ingress.
Managed certificate not provisioned when domain resolves to IP addresses of multiple load balancers
When your domain resolves to IP addresses of multiple load balancers (multiple
Ingress objects), you should create a single ManagedCertificate
object and
attach it to all the Ingress objects. If you instead create many
ManagedCertificate
objects and attach each of them to a separate Ingress, the
Certificate Authority might not be able to verify the ownership of your domain
and some of your certificates might not be provisioned. For the verification to
be successful, the certificate must be visible under all the IP addresses to
which your domain resolves to.
Specifically, when your domain resolves to an IPv4 and an IPv6 addresses which
are configured with different Ingress objects, you should create a single
ManagedCertificate
object and attach it to both Ingresses.
Disrupted communication between Google-managed certificates and Ingress
Managed certificates communicate with Ingress using the
ingress.gcp.kubernetes.io/pre-shared-cert
annotation. You can disrupt this communication
if you, for example:
- Run an automated process that clears the
ingress.gcp.kubernetes.io/pre-shared-cert
annotation. - Store a snapshot of Ingress then delete and restore the Ingress from the
snapshot. In the meantime, an
SslCertificate
resource listed in theingress.gcp.kubernetes.io/pre-shared-cert
annotation might have been deleted. Ingress does not work if any certificates attached to it are missing.
If communication between Google-managed certificates and Ingress is disrupted,
delete the contents of the ingress.gcp.kubernetes.io/pre-shared-cert
annotation and wait
for the system to reconcile. To prevent recurrence, ensure that the annotation
is not inadvertently modified or deleted.
Validation errors when creating a Google-managed certificate
ManagedCertificate
definitions are validated before the ManagedCertificate
object is created. If validation fails, the ManagedCertificate
object is
not created and an error message is printed. The different error messages and
reasons are explained as follows:
spec.domains in body should have at most 100 items
Your ManagedCertificate
manifest lists more than 100 domains in the
spec.domains
field. Google-managed certificates support only up to 100 domains.
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. The ManagedCertificate
object does not support
wildcard domains (for example, *.example.com
).
spec.domains in body should be at most 63 chars long
You specified a domain name that is too long. Google-managed certificates support domain names with at most 63 characters.
Manually updating a Google-managed certificate
To manually update the certificate so that the certificate for the old domain continues to work until the certificate for the new domain is provisioned, follow these steps:
- Create a
ManagedCertificate
for the new domain. - Add the name of the
ManagedCertificate
to thenetworking.gke.io/managed-certificates
annotation on the Ingress using a comma-separated list. Don't remove the old certificate name. - Wait until the
ManagedCertificate
becomes Active. - Detach the old certificate from the Ingress and delete it.
When you create a ManagedCertificate
, Google Cloud creates a
Google-managed SSL certificate. You cannot update this certificate. If you
update the ManagedCertificate
, Google Cloud deletes and recreates the
Google-managed SSL certificate.
To provide secure HTTPS encrypted Ingress for your GKE clusters, see example Secure Ingress.
What's next
- Learn more about Google-managed certificates.
- Learn how to set up an external Application Load Balancer with Ingress.
- Learn how to Use multiple SSL certificates with external Application Load Balancers with Ingress.
- Implement a secure Ingress.