Learn how to configure Knative serving to use your own SSL/TLS certificates.

Alternatively, you can use the
[managed TLS certificates](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/managed-tls.md.txt) feature, which
automatically creates and renews TLS certificates through
[Let's Encrypt](https://letsencrypt.org/)

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 must configure a custom domain. For details, see [Mapping custom domains](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/mapping-custom-domains.md.txt).
- You are required to configure each of your Knative serving services that use the [ingress gateway](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/architecture-overview.md.txt#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.

## Storing TLS certificates in a Kubernetes Secret

To store the certificates into a Secret:

1. Open a terminal and navigate to the directory where your TLS certificates
   are located.

2. Use the following command to create a secret that stores your certificates:

   ```bash
   kubectl create --namespace INGRESS_NAMESPACE secret tls SECRET_NAME \
     --key PRIVATE_KEY.pem \
     --cert FULL_CHAIN.pem
   ```

   Replace:
   - <var translate="no">INGRESS_NAMESPACE</var> with the namespace of your ingress service, `istio-ingressgateway`. Specify the `istio-system` namespace if you installed Cloud Service Mesh using the default configuration.
   - <var translate="no">SECRET_NAME</var> with the name that you want use for your Kubernetes Secret.
   - <var translate="no">PRIVATE_KEY.pem</var> with the name of the file that holds your certificate private key.
   - <var translate="no">FULL_CHAIN.pem</var> with 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:

1. Open the ingress gateway YAML in edit mode by running the following command:

   ```bash
   kubectl edit gateway knative-ingress-gateway --namespace knative-serving
   ```

   Example of the default ingress gateway configuration:

   ```yaml
   apiVersion: networking.istio.io/v1beta1
   kind: Gateway
   metadata:
     ...
     # other skipped configuration
     ...
   spec:
     selector:
       istio: ingressgateway
     servers:
     - hosts:
       - '*'
       port:
         name: http
         number: 80
         protocol: HTTP
   ```
2. Configure the ingress gateway to use your secret by appending the `hosts`,
   `port`, and `tls` attributes to the existing YAML.

   - **To configure all services to use the same secret** : Append the following
     to your YAML configuration and specify `"*"` as the `hosts` attribute
     value:

     ```yaml
     ...
     # other skipped configuration
     ...
     - hosts:
       - "*"
       port:
         name: https
         number: 443
         protocol: HTTPS
       tls:
         mode: SIMPLE
         credentialName: SECRET_NAME
     ```

     Replace <var translate="no">SECRET_NAME</var> with the name of the secret
     that you created.

     [See example](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/bring-your-own-cert.md.txt#example_all).
   - **To individually configure each of your services** : Append the following
     to your YAML configuration and specify the values for the `hosts`
     attributes using the service's name and namespace:

     For each service, you specify values for the `hosts`, `port`, and `tls`
     attributes:

     ```yaml
     ...
     # other skipped configuration
     ...
     - hosts:
       - SERVICE_NAME.SERVICE_NAMESPACE.CUSTOM_DOMAIN
       port:
         number: 443
         name: https-SERVICE_NAME
         protocol: HTTPS
       tls:
         mode: SIMPLE
         credentialName: SECRET_NAME
     ```

     Replace:
     - <var translate="no">SERVICE_NAME</var> with the name of the Knative serving service. Every service that uses the ingress gateway to serve external traffic must be individually configured.
     - <var translate="no">SERVICE_NAMESPACE</var> with the name of the namespace in which the service is running.
     - <var translate="no">CUSTOM_DOMAIN</var> with the custom domain for which you configured the service to use.
     - <var translate="no">SECRET_NAME</var> 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.

     [See example](https://docs.cloud.google.com/kubernetes-engine/enterprise/knative-serving/docs/bring-your-own-cert.md.txt#example_individual).
3. Save your changes.

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 the
    `TLSsecret` secret:

    ```yaml
    apiVersion: networking.istio.io/v1alpha3
    kind: Gateway
    metadata:
      ...
      # other skipped configuration
      ...
    spec:
      selector:
        istio: ingressgateway
      servers:
        - hosts:
          - "*"
          port:
            name: http
            number: 80
            protocol: HTTP
        - hosts:
          - "*"
          port:
            name: https
            number: 443
            protocol: HTTPS
          tls:
            mode: SIMPLE
            credentialName: TLSsecret
    ```

Configure individual services:

:   This example demonstrates how to individually configure all three of the
    services that are serving internet traffic:

    ```yaml
    apiVersion: networking.istio.io/v1alpha3
    kind: Gateway
    metadata:
      ...
      # other skipped configuration
      ...
    spec:
      selector:
        istio: ingressgateway
      servers:
      - hosts:
        - "*"
        port:
          name: http
          number: 80
          protocol: HTTP
      - hosts:
        - prodservice.prodnamespace.my-custom-domain.com
        port:
          number: 443
          name: https-prodservice
          protocol: HTTPS
        tls:
          mode: SIMPLE
          credentialName: TLSsecret
      - hosts:
        - experiment.namespace.my-custom-domain.com
        port:
          number: 443
          name: https-experiment
          protocol: HTTPS
        tls:
          mode: SIMPLE
          credentialName: TLSsecret
      - hosts:
        - fallbackservice.anothernamespace.my-custom-domain.com
        port:
          number: 443
          name: https-fallbackservice
          protocol: HTTPS
        tls:
          mode: SIMPLE
          credentialName: anotherTLSsecret
    ```