github.com/projectcontour/contour@v1.28.2/site/content/docs/v1.1.0/grpc-tls-howto.md (about)

     1  # Enabling TLS between Envoy and Contour
     2  
     3  This document describes the steps required to secure communication between Envoy and Contour.
     4  The outcome of this is that we will have three Secrets available in the `projectcontour` namespace:
     5  
     6  - **cacert:** contains the CA's public certificate.
     7  - **contourcert:** contains Contour's keypair, used for serving TLS secured gRPC. This must be a valid certificate for the name `contour` in order for this to work. This is currently hardcoded by Contour.
     8  - **envoycert:** contains Envoy's keypair, used as a client for connecting to Contour.
     9  
    10  ## Ways you can get the certificates into your cluster
    11  
    12  - Deploy the Job from [certgen.yaml][1].
    13  This will run `contour certgen --kube` for you.
    14  - Run `contour certgen --kube` locally.
    15  - Run the manual procedure below.
    16  
    17  ## Caveats and warnings
    18  
    19  **Be very careful with your production certificates!**
    20  
    21  This is intended as an example to help you get started. For any real deployment, you should **carefully** manage all the certificates and control who has access to them. Make sure you don't commit them to any git repos either.
    22  
    23  ## Manual TLS certificate generation process
    24  
    25  ### Generating a CA keypair
    26  
    27  First, we need to generate a keypair:
    28  
    29  ```
    30  $ openssl req -x509 -new -nodes \
    31      -keyout certs/cakey.pem -sha256 \
    32      -days 1825 -out certs/cacert.pem \
    33      -subj "/O=Project Contour/CN=Contour CA"
    34  ```
    35  
    36  Then, the new CA key will be stored in `certs/cakey.pem` and the cert in `certs/cacert.pem`.
    37  
    38  ### Generating Contour's keypair
    39  
    40  Then, we need to generate a keypair for Contour. First, we make a new private key:
    41  
    42  ```
    43  $ openssl genrsa -out certs/contourkey.pem 2048
    44  ```
    45  
    46  Then, we create a CSR and have our CA sign the CSR and issue a cert. This uses the file [_integration/cert-contour.ext][2], which ensures that at least one of the valid names of the certificate is the bareword `contour`. This is required for the handshake to succeed, as `contour bootstrap` configures Envoy to pass this as the SNI for the connection.
    47  
    48  ```
    49  $ openssl req -new -key certs/contourkey.pem \
    50  	-out certs/contour.csr \
    51  	-subj "/O=Project Contour/CN=contour"
    52  
    53  $ openssl x509 -req -in certs/contour.csr \
    54      -CA certs/cacert.pem \
    55      -CAkey certs/cakey.pem \
    56      -CAcreateserial \
    57      -out certs/contourcert.pem \
    58      -days 1825 -sha256 \
    59      -extfile _integration/cert-contour.ext
    60  ```
    61  
    62  At this point, the contour cert and key are in the files `certs/contourcert.pem` and `certs/contourkey.pem` respectively.
    63  
    64  ### Generating Envoy's keypair
    65  
    66  Next, we generate a keypair for Envoy:
    67  
    68  ```
    69  $ openssl genrsa -out certs/envoykey.pem 2048
    70  ```
    71  
    72  Then, we generated a CSR and have the CA sign it:
    73  
    74  ```
    75  $ openssl req -new -key certs/envoykey.pem \
    76  	-out certs/envoy.csr \
    77  	-subj "/O=Project Contour/CN=envoy"
    78  
    79  $ openssl x509 -req -in certs/envoy.csr \
    80      -CA certs/cacert.pem \
    81      -CAkey certs/cakey.pem \
    82      -CAcreateserial \
    83      -out certs/envoycert.pem \
    84      -days 1825 -sha256 \
    85      -extfile _integration/cert-envoy.ext
    86  ```
    87  
    88  Like the contour cert, this CSR uses the file [_integration/cert-envoy.ext][3]. However, in this case, there are no special names required.
    89  
    90  ### Putting the certs in the cluster
    91  
    92  Next, we create the required secrets in the target Kubernetes cluster:
    93  
    94  ```
    95  $ kubectl create secret -n projectcontour generic cacert \
    96          --from-file=./certs/cacert.pem
    97  
    98  $ kubectl create secret -n projectcontour tls contourcert \
    99          --key=./certs/contourkey.pem --cert=./certs/contourcert.pem
   100  
   101  $ kubectl create secret -n projectcontour tls envoycert \
   102          --key=./certs/envoykey.pem --cert=./certs/envoycert.pem
   103  ```
   104  
   105  Note that we don't put the CA **key** into the cluster, there's no reason for that to be there, and that would create a security problem. That also means that the `cacert` secret can't be a `tls` type secret, as they must be a keypair.
   106  
   107  # Conclusion
   108  
   109  Once this process is done, the certificates will be present as Secrets in the `projectcontour` namespace, as required by
   110  [examples/contour][4].
   111  
   112  [1]: {{< param github_url >}}/tree/{{page.version}}/examples/contour/02-job-certgen.yaml
   113  [2]: {{< param github_url >}}/tree/{{page.version}}/_integration/cert-contour.ext
   114  [3]: {{< param github_url >}}/tree/{{page.version}}/_integration/cert-envoy.ext
   115  [4]: {{< param github_url >}}/tree/{{page.version}}/examples/contour