To use your own certificates, you store your TLS certificates in a Kubernetes
Secret and then configure the ingress gateway of Cloud Service Mesh to use that
secret.
Before you begin
These instructions assume that you have already obtained your TLS
certificates.
You are required to configure each of your Knative serving services
that use theingress gatewayto serve external traffic. If these external facing services are not
configured to use your TLS certificates, the services will not be able to
verify an HTTPS connection and therefore, never achieve thereadystate.
Storing TLS certificates in a Kubernetes Secret
To store the certificates into a Secret:
Open a terminal and navigate to the directory where your TLS certificates
are located.
Use the following command to create a secret that stores your certificates:
INGRESS_NAMESPACEwith the namespace of your
ingress service,istio-ingressgateway. Specify theistio-systemnamespace if you installed Cloud Service Mesh using the default configuration.
SECRET_NAMEwith the name that you want use for your
Kubernetes Secret.
PRIVATE_KEY.pemwith the name of the file that holds your
certificate private key.
FULL_CHAIN.pemwith the name of the file that holds your
public certificate.
You can now configure the ingress gateway to use the secret you just created
for your TLS certificate.
Configuring the ingress gateway to use your certificates
Modify the ingress gateway of Cloud Service Mesh to use the secret that you created
for your TLS certificates:
Open the ingress gateway YAML in edit mode by running the following command:
Example of the default ingress gateway configuration:
apiVersion:networking.istio.io/v1beta1kind:Gatewaymetadata:...# other skipped configuration...spec:selector:istio:ingressgatewayservers:-hosts:-'*'port:name:httpnumber:80protocol:HTTP
Configure the ingress gateway to use your secret by appending thehosts,port, andtlsattributes to the existing YAML.
To configure all services to use the same secret: Append the following
to your YAML configuration and specify"*"as thehostsattribute
value:
...# other skipped configuration...-hosts:-"*"port:name:httpsnumber:443protocol:HTTPStls:mode:SIMPLEcredentialName:SECRET_NAME
ReplaceSECRET_NAMEwith the name of the secret
that you created.
To individually configure each of your services: Append the following
to your YAML configuration and specify the values for thehostsattributes using the service's name and namespace:
For each service, you specify values for thehosts,port, andtlsattributes:
...# other skipped configuration...-hosts:-SERVICE_NAME.SERVICE_NAMESPACE.CUSTOM_DOMAINport:number:443name:https-SERVICE_NAMEprotocol:HTTPStls:mode:SIMPLEcredentialName:SECRET_NAME
Replace:
SERVICE_NAMEwith the name of the Knative serving
service. Every service that uses the ingress gateway to serve external
traffic must be individually configured.
SERVICE_NAMESPACEwith the name of the namespace
in which the service is running.
CUSTOM_DOMAINwith the custom domain for which you
configured the service to use.
SECRET_NAMEwith the name of the secret that you
want the service to use. If you created multiple secrets for different
sets of TLS certificates, you can specify which secret each service uses.
You can now use the HTTPS protocol to access your deployed Knative serving
services.
Examples
Configure all services:
This example demonstrates how to configure all services to use theTLSsecretsecret:
apiVersion:networking.istio.io/v1alpha3kind:Gatewaymetadata:...# other skipped configuration...spec:selector:istio:ingressgatewayservers:-hosts:-"*"port:name:httpnumber:80protocol:HTTP-hosts:-"*"port:name:httpsnumber:443protocol:HTTPStls:mode:SIMPLEcredentialName:TLSsecret
Configure individual services:
This example demonstrates how to individually configure all three of the
services that are serving internet traffic:
apiVersion:networking.istio.io/v1alpha3kind:Gatewaymetadata:...# other skipped configuration...spec:selector:istio:ingressgatewayservers:-hosts:-"*"port:name:httpnumber:80protocol:HTTP-hosts:-prodservice.prodnamespace.my-custom-domain.comport:number:443name:https-prodserviceprotocol:HTTPStls:mode:SIMPLEcredentialName:TLSsecret-hosts:-experiment.namespace.my-custom-domain.comport:number:443name:https-experimentprotocol:HTTPStls:mode:SIMPLEcredentialName:TLSsecret-hosts:-fallbackservice.anothernamespace.my-custom-domain.comport:number:443name:https-fallbackserviceprotocol:HTTPStls:mode:SIMPLEcredentialName:anotherTLSsecret
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Using your own TLS certificates\n\nLearn how to configure Knative serving to use your own SSL/TLS certificates.\n\nAlternatively, you can use the\n[managed TLS certificates](/kubernetes-engine/enterprise/knative-serving/docs/managed-tls) feature, which\nautomatically creates and renews TLS certificates through\n[Let's Encrypt](https://letsencrypt.org/)\n\nTo use your own certificates, you store your TLS certificates in a Kubernetes\nSecret and then configure the ingress gateway of Cloud Service Mesh to use that\nsecret.\n\nBefore you begin\n----------------\n\n- These instructions assume that you have already obtained your TLS certificates.\n- You must configure a custom domain. For details, see [Mapping custom domains](/kubernetes-engine/enterprise/knative-serving/docs/mapping-custom-domains).\n- You are required to configure each of your Knative serving services that use the [ingress gateway](/kubernetes-engine/enterprise/knative-serving/docs/architecture-overview#components_in_the_default_installation) to serve external traffic. If these external facing services are not configured to use your TLS certificates, the services will not be able to verify an HTTPS connection and therefore, never achieve the `ready` state.\n\nStoring TLS certificates in a Kubernetes Secret\n-----------------------------------------------\n\nTo store the certificates into a Secret:\n\n1. Open a terminal and navigate to the directory where your TLS certificates\n are located.\n\n2. Use the following command to create a secret that stores your certificates:\n\n ```bash\n kubectl create --namespace INGRESS_NAMESPACE secret tls SECRET_NAME \\\n --key PRIVATE_KEY.pem \\\n --cert FULL_CHAIN.pem\n ```\n\n Replace:\n - \u003cvar translate=\"no\"\u003eINGRESS_NAMESPACE\u003c/var\u003e with the namespace of your ingress service, `istio-ingressgateway`. Specify the `istio-system` namespace if you installed Cloud Service Mesh using the default configuration.\n - \u003cvar translate=\"no\"\u003eSECRET_NAME\u003c/var\u003e with the name that you want use for your Kubernetes Secret.\n - \u003cvar translate=\"no\"\u003ePRIVATE_KEY.pem\u003c/var\u003e with the name of the file that holds your certificate private key.\n - \u003cvar translate=\"no\"\u003eFULL_CHAIN.pem\u003c/var\u003e with the name of the file that holds your public certificate.\n\nYou can now configure the ingress gateway to use the secret you just created\nfor your TLS certificate.\n\nConfiguring the ingress gateway to use your certificates\n--------------------------------------------------------\n\nModify the ingress gateway of Cloud Service Mesh to use the secret that you created\nfor your TLS certificates:\n\n1. Open the ingress gateway YAML in edit mode by running the following command:\n\n ```bash\n kubectl edit gateway knative-ingress-gateway --namespace knative-serving\n ```\n\n Example of the default ingress gateway configuration: \n\n apiVersion: networking.istio.io/v1beta1\n kind: Gateway\n metadata:\n ...\n # other skipped configuration\n ...\n spec:\n selector:\n istio: ingressgateway\n servers:\n - hosts:\n - '*'\n port:\n name: http\n number: 80\n protocol: HTTP\n\n2. Configure the ingress gateway to use your secret by appending the `hosts`,\n `port`, and `tls` attributes to the existing YAML.\n\n - **To configure all services to use the same secret** : Append the following\n to your YAML configuration and specify `\"*\"` as the `hosts` attribute\n value:\n\n ...\n # other skipped configuration\n ...\n - hosts:\n - \"*\"\n port:\n name: https\n number: 443\n protocol: HTTPS\n tls:\n mode: SIMPLE\n credentialName: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eSECRET_NAME\u003c/span\u003e\u003c/var\u003e\n\n Replace \u003cvar translate=\"no\"\u003eSECRET_NAME\u003c/var\u003e with the name of the secret\n that you created.\n\n [See example](#example_all).\n - **To individually configure each of your services** : Append the following\n to your YAML configuration and specify the values for the `hosts`\n attributes using the service's name and namespace:\n\n For each service, you specify values for the `hosts`, `port`, and `tls`\n attributes: \n\n ...\n # other skipped configuration\n ...\n - hosts:\n - \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eSERVICE_NAME\u003c/span\u003e\u003c/var\u003e.\u003cvar translate=\"no\"\u003eSERVICE_NAMESPACE\u003c/var\u003e.\u003cvar translate=\"no\"\u003eCUSTOM_DOMAIN\u003c/var\u003e\n port:\n number: 443\n name: https-\u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e\n protocol: HTTPS\n tls:\n mode: SIMPLE\n credentialName: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eSECRET_NAME\u003c/span\u003e\u003c/var\u003e\n\n Replace:\n - \u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e with the name of the Knative serving service. Every service that uses the ingress gateway to serve external traffic must be individually configured.\n - \u003cvar translate=\"no\"\u003eSERVICE_NAMESPACE\u003c/var\u003e with the name of the namespace in which the service is running.\n - \u003cvar translate=\"no\"\u003eCUSTOM_DOMAIN\u003c/var\u003e with the custom domain for which you configured the service to use.\n - \u003cvar translate=\"no\"\u003eSECRET_NAME\u003c/var\u003e with the name of the secret that you want the service to use. If you created multiple secrets for different sets of TLS certificates, you can specify which secret each service uses.\n\n [See example](#example_individual).\n3. Save your changes.\n\nYou can now use the HTTPS protocol to access your deployed Knative serving\nservices.\n\nExamples\n--------\n\nConfigure all services:\n\n: This example demonstrates how to configure all services to use the\n `TLSsecret` secret:\n\n apiVersion: networking.istio.io/v1alpha3\n kind: Gateway\n metadata:\n ...\n # other skipped configuration\n ...\n spec:\n selector:\n istio: ingressgateway\n servers:\n - hosts:\n - \"*\"\n port:\n name: http\n number: 80\n protocol: HTTP\n - hosts:\n - \"*\"\n port:\n name: https\n number: 443\n protocol: HTTPS\n tls:\n mode: SIMPLE\n credentialName: TLSsecret\n\nConfigure individual services:\n\n: This example demonstrates how to individually configure all three of the\n services that are serving internet traffic:\n\n apiVersion: networking.istio.io/v1alpha3\n kind: Gateway\n metadata:\n ...\n # other skipped configuration\n ...\n spec:\n selector:\n istio: ingressgateway\n servers:\n - hosts:\n - \"*\"\n port:\n name: http\n number: 80\n protocol: HTTP\n - hosts:\n - prodservice.prodnamespace.my-custom-domain.com\n port:\n number: 443\n name: https-prodservice\n protocol: HTTPS\n tls:\n mode: SIMPLE\n credentialName: TLSsecret\n - hosts:\n - experiment.namespace.my-custom-domain.com\n port:\n number: 443\n name: https-experiment\n protocol: HTTPS\n tls:\n mode: SIMPLE\n credentialName: TLSsecret\n - hosts:\n - fallbackservice.anothernamespace.my-custom-domain.com\n port:\n number: 443\n name: https-fallbackservice\n protocol: HTTPS\n tls:\n mode: SIMPLE\n credentialName: anotherTLSsecret"]]
