From 1531c94cd1eea0c09a730a35d9aa268653667c66 Mon Sep 17 00:00:00 2001 From: mattmoor-sockpuppet Date: Thu, 6 Jun 2019 09:19:41 -0700 Subject: [PATCH] Format markdown (#1424) * Format markdown Produced via: `prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github)` * Remove redundant bullet --- docs/install/Knative-with-GKE.md | 7 +- docs/install/Knative-with-Minikube.md | 96 ++++----- docs/install/README.md | 2 +- docs/serving/using-auto-tls.md | 268 +++++++++++++------------- 4 files changed, 187 insertions(+), 186 deletions(-) diff --git a/docs/install/Knative-with-GKE.md b/docs/install/Knative-with-GKE.md index d321bfdcc..76529cc52 100644 --- a/docs/install/Knative-with-GKE.md +++ b/docs/install/Knative-with-GKE.md @@ -121,9 +121,10 @@ the recommended configuration for a cluster is: > [Gloo](./Knative-with-Gloo.md)) will be used, then you can remove the > `--addons` line below. -> Note: If you want to use [Auto TLS feature](../serving/using-auto-tls.md), you need to remove -> the `--addons` line below, and follow the [instructions](installing-istio.md) to install Istio -> with Secret Discovery Service. +> Note: If you want to use [Auto TLS feature](../serving/using-auto-tls.md), you +> need to remove the `--addons` line below, and follow the +> [instructions](installing-istio.md) to install Istio with Secret Discovery +> Service. ```bash gcloud beta container clusters create $CLUSTER_NAME \ diff --git a/docs/install/Knative-with-Minikube.md b/docs/install/Knative-with-Minikube.md index 48a980a2f..107d7020d 100644 --- a/docs/install/Knative-with-Minikube.md +++ b/docs/install/Knative-with-Minikube.md @@ -99,71 +99,73 @@ see [Performing a Custom Knative Installation](./Knative-custom-install.md). of `knative-ingressgateway`. Then run the following to clean up leftover resources: - ```shell - kubectl delete svc knative-ingressgateway -n istio-system - kubectl delete deploy knative-ingressgateway -n istio-system - ``` + ```shell + kubectl delete svc knative-ingressgateway -n istio-system + kubectl delete deploy knative-ingressgateway -n istio-system + ``` - If you have the Knative Eventing Sources component installed, you will also - need to delete the following resource before upgrading: + If you have the Knative Eventing Sources component installed, you will also + need to delete the following resource before upgrading: - ```shell - kubectl delete statefulset/controller-manager -n knative-sources - ``` + ```shell + kubectl delete statefulset/controller-manager -n knative-sources + ``` - While the deletion of this resource during the upgrade process will not - prevent modifications to Eventing Source resources, those changes will not be - completed until the upgrade process finishes. + While the deletion of this resource during the upgrade process will not + prevent modifications to Eventing Source resources, those changes will not be + completed until the upgrade process finishes. 1. To install Knative, first install the CRDs by running the `kubectl apply` command once with the `-l knative.dev/crd-install=true` flag. This prevents race conditions during the install, which cause intermittent errors: - ```shell - kubectl apply --selector knative.dev/crd-install=true \ - --filename https://github.com/knative/serving/releases/download/v0.6.0/serving.yaml \ - --filename https://github.com/knative/build/releases/download/v0.5.0/build.yaml \ - --filename https://github.com/knative/eventing/releases/download/v0.5.0/release.yaml \ - --filename https://github.com/knative/eventing-sources/releases/download/v0.5.0/eventing-sources.yaml \ - --filename https://github.com/knative/serving/releases/download/v0.6.0/monitoring.yaml \ - --filename https://raw.githubusercontent.com/knative/serving/v0.6.0/third_party/config/build/clusterrole.yaml - ``` + ```shell + kubectl apply --selector knative.dev/crd-install=true \ + --filename https://github.com/knative/serving/releases/download/v0.6.0/serving.yaml \ + --filename https://github.com/knative/build/releases/download/v0.5.0/build.yaml \ + --filename https://github.com/knative/eventing/releases/download/v0.5.0/release.yaml \ + --filename https://github.com/knative/eventing-sources/releases/download/v0.5.0/eventing-sources.yaml \ + --filename https://github.com/knative/serving/releases/download/v0.6.0/monitoring.yaml \ + --filename https://raw.githubusercontent.com/knative/serving/v0.6.0/third_party/config/build/clusterrole.yaml + ``` 1. To complete the install of Knative and its dependencies, run the `kubectl apply` command again, this time without the `--selector` flag, to complete the install of Knative and its dependencies: - ```shell - kubectl apply --filename https://github.com/knative/serving/releases/download/v0.6.0/serving.yaml --selector networking.knative.dev/certificate-provider!=cert-manager \ - --filename https://github.com/knative/build/releases/download/v0.5.0/build.yaml \ - --filename https://github.com/knative/eventing/releases/download/v0.5.0/release.yaml \ - --filename https://github.com/knative/eventing-sources/releases/download/v0.5.0/eventing-sources.yaml \ - --filename https://github.com/knative/serving/releases/download/v0.6.0/monitoring.yaml \ - --filename https://raw.githubusercontent.com/knative/serving/v0.6.0/third_party/config/build/clusterrole.yaml - ``` + ```shell + kubectl apply --filename https://github.com/knative/serving/releases/download/v0.6.0/serving.yaml --selector networking.knative.dev/certificate-provider!=cert-manager \ + --filename https://github.com/knative/build/releases/download/v0.5.0/build.yaml \ + --filename https://github.com/knative/eventing/releases/download/v0.5.0/release.yaml \ + --filename https://github.com/knative/eventing-sources/releases/download/v0.5.0/eventing-sources.yaml \ + --filename https://github.com/knative/serving/releases/download/v0.6.0/monitoring.yaml \ + --filename https://raw.githubusercontent.com/knative/serving/v0.6.0/third_party/config/build/clusterrole.yaml + ``` - > **Notes**: - > - By default, the Knative Serving component installation (`serving.yaml`) includes a controller - > for [enabling automatic TLS certificate provisioning](../serving/using-auto-tls.md). If you do - > intend on immediately enabling auto certificates in Knative, you can remove the - > `--selector networking.knative.dev/certificate-provider!=cert-manager` statement to install the - > controller. - > Otherwise, you can choose to install the auto certificates feature and controller at a later time. - > - > - For the v0.4.0 release and newer, the `clusterrole.yaml` file is - > required to enable the Build and Serving components to interact with each - > other. + > **Notes**: + > + > - By default, the Knative Serving component installation (`serving.yaml`) + > includes a controller for + > [enabling automatic TLS certificate provisioning](../serving/using-auto-tls.md). + > If you do intend on immediately enabling auto certificates in Knative, + > you can remove the + > `--selector networking.knative.dev/certificate-provider!=cert-manager` + > statement to install the controller. Otherwise, you can choose to install + > the auto certificates feature and controller at a later time. + > + > - For the v0.4.0 release and newer, the `clusterrole.yaml` file is required + > to enable the Build and Serving components to interact with each other. 1. Monitor the Knative components until all of the components show a `STATUS` of `Running`: - ```shell - kubectl get pods --namespace knative-serving - kubectl get pods --namespace knative-build - kubectl get pods --namespace knative-eventing - kubectl get pods --namespace knative-sources - kubectl get pods --namespace knative-monitoring - ``` + ```shell + kubectl get pods --namespace knative-serving + kubectl get pods --namespace knative-build + kubectl get pods --namespace knative-eventing + kubectl get pods --namespace knative-sources + kubectl get pods --namespace knative-monitoring + ``` ## Deploying an app diff --git a/docs/install/README.md b/docs/install/README.md index 83ce7407b..86eb0e0a3 100644 --- a/docs/install/README.md +++ b/docs/install/README.md @@ -4,7 +4,7 @@ Follow this guide to install Knative components on a platform of your choice. To get started with Knative, you need a Kubernetes cluster. If you aren't sure which Kubernetes platform is right for you, see -[Picking the Right Solution]( https://kubernetes.io/docs/setup/). +[Picking the Right Solution](https://kubernetes.io/docs/setup/). We provide information for installing Knative on [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/docs/), diff --git a/docs/serving/using-auto-tls.md b/docs/serving/using-auto-tls.md index 3a314554e..3710a4997 100644 --- a/docs/serving/using-auto-tls.md +++ b/docs/serving/using-auto-tls.md @@ -31,187 +31,191 @@ To enable Knative to automatically provision TLS certificates: 1. Determine if `networking-certmanager` is installed by running the following command: - ```shell - kubectl get deployment networking-certmanager -n knative-serving - ``` + ```shell + kubectl get deployment networking-certmanager -n knative-serving + ``` -1. If `networking-certmanager` is not found, run the following commands to install it: +1. If `networking-certmanager` is not found, run the following commands to + install it: - ```shell - # KNATIVE_VERSION needs to be 0.6.0 or above. - KNATIVE_VERSION=0.6.0 + ```shell + # KNATIVE_VERSION needs to be 0.6.0 or above. + KNATIVE_VERSION=0.6.0 - kubectl apply --filename https://github.com/knative/serving/releases/download/v${KNATIVE_VERSION}/serving.yaml \ - --selector networking.knative.dev/certificate-provider=cert-manager - ``` + kubectl apply --filename https://github.com/knative/serving/releases/download/v${KNATIVE_VERSION}/serving.yaml \ + --selector networking.knative.dev/certificate-provider=cert-manager + ``` 1. Create and add the `ClusterIssuer` configuration file to your Knative cluster to define who issues the TLS certificates, how requests are validated (`DNS-01`), and which DNS provider validates those requests. - 1. Create the `ClusterIssuer` file: + 1. Create the `ClusterIssuer` file: - Use the cert-manager reference to determine how to configure your `ClusterIssuer` file: + Use the cert-manager reference to determine how to configure your + `ClusterIssuer` file: - - See the generic - [`ClusterIssuer` example](https://docs.cert-manager.io/en/latest/tasks/issuers/setup-acme.html#creating-a-basic-acme-issuer) - - Also see the [`DNS-01` example](https://docs.cert-manager.io/en/latest/tasks/acme/configuring-dns01/index.html) + - See the generic + [`ClusterIssuer` example](https://docs.cert-manager.io/en/latest/tasks/issuers/setup-acme.html#creating-a-basic-acme-issuer) + - Also see the + [`DNS-01` example](https://docs.cert-manager.io/en/latest/tasks/acme/configuring-dns01/index.html) - **Example**: Cloud DNS `ClusterIssuer` configuration file: + **Example**: Cloud DNS `ClusterIssuer` configuration file: - The following `letsencrypt-issuer` named `ClusterIssuer` file is configured - for the Let's Encrypt CA and Google Cloud DNS. Under `spec`, the Let's Encrypt - account info, required `DNS-01` challenge type, and Cloud DNS provider - info defined. For the complete Google Cloud DNS example, see - [Configuring HTTPS with cert-manager and Google Cloud DNS](./using-cert-manager-on-gcp.md). + The following `letsencrypt-issuer` named `ClusterIssuer` file is + configured for the Let's Encrypt CA and Google Cloud DNS. Under `spec`, + the Let's Encrypt account info, required `DNS-01` challenge type, and + Cloud DNS provider info defined. For the complete Google Cloud DNS + example, see + [Configuring HTTPS with cert-manager and Google Cloud DNS](./using-cert-manager-on-gcp.md). - ```shell - apiVersion: certmanager.k8s.io/v1alpha1 - kind: ClusterIssuer - metadata: - name: letsencrypt-issuer - namespace: cert-manager - spec: - acme: - server: https://acme-v02.api.letsencrypt.org/directory - # This will register an issuer with LetsEncrypt. Replace - # with your admin email address. - email: myemail@gmail.com - privateKeySecretRef: - # Set privateKeySecretRef to any unused secret name. - name: letsencrypt-issuer - dns01: - providers: - - name: cloud-dns-provider - clouddns: - # Set this to your GCP project-id - project: $PROJECT_ID - # Set this to the secret that we publish our service account key - # in the previous step. - serviceAccountSecretRef: - name: cloud-dns-key - key: key.json - ``` + ```shell + apiVersion: certmanager.k8s.io/v1alpha1 + kind: ClusterIssuer + metadata: + name: letsencrypt-issuer + namespace: cert-manager + spec: + acme: + server: https://acme-v02.api.letsencrypt.org/directory + # This will register an issuer with LetsEncrypt. Replace + # with your admin email address. + email: myemail@gmail.com + privateKeySecretRef: + # Set privateKeySecretRef to any unused secret name. + name: letsencrypt-issuer + dns01: + providers: + - name: cloud-dns-provider + clouddns: + # Set this to your GCP project-id + project: $PROJECT_ID + # Set this to the secret that we publish our service account key + # in the previous step. + serviceAccountSecretRef: + name: cloud-dns-key + key: key.json + ``` 1. Add your `ClusterIssuer` configuration to your Knative cluster by running the following commands, where `` is the name of the file that you created: - 1. Add the configuration file to Knative: + 1. Add the configuration file to Knative: - ```shell - kubectl apply -f .yaml - ``` + ```shell + kubectl apply -f .yaml + ``` 1. Ensure that the file is created successfully: - ```shell - kubectl get clusterissuer --namespace cert-manager letsencrypt-issuer --output yaml - ``` + ```shell + kubectl get clusterissuer --namespace cert-manager letsencrypt-issuer --output yaml + ``` - Result: The `Status.Conditions` should include `Ready=True`. + Result: The `Status.Conditions` should include `Ready=True`. 1. Update your [`config-certmanager` ConfigMap](https://github.com/knative/serving/blob/master/config/config-certmanager.yaml) in the `knative-serving` namespace to define your new `ClusterIssuer` configuration and your your DNS provider. - 1. Run the following command to edit your `config-certmanager` ConfigMap: + 1. Run the following command to edit your `config-certmanager` ConfigMap: - ```shell - kubectl edit configmap config-certmanager --namespace knative-serving - ``` + ```shell + kubectl edit configmap config-certmanager --namespace knative-serving + ``` - 1. Add the `issuerRef` and `solverConfig` sections within the `data` section: + 1. Add the `issuerRef` and `solverConfig` sections within the `data` section: - ```shell - ... - data: - ... - issuerRef: | - kind: ClusterIssuer - name: letsencrypt-issuer + ```shell + ... + data: + ... + issuerRef: | + kind: ClusterIssuer + name: letsencrypt-issuer - solverConfig: | - dns01: - provider: cloud-dns-provider - ``` + solverConfig: | + dns01: + provider: cloud-dns-provider + ``` - Example: + Example: - ```shell - apiVersion: v1 - kind: ConfigMap - metadata: - name: config-certmanager - namespace: knative-serving - labels: - networking.knative.dev/certificate-provider: cert-manager - data: - issuerRef: | - kind: ClusterIssuer - name: letsencrypt-issuer - solverConfig: | - dns01: - provider: cloud-dns-provider - ``` + ```shell + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-certmanager + namespace: knative-serving + labels: + networking.knative.dev/certificate-provider: cert-manager + data: + issuerRef: | + kind: ClusterIssuer + name: letsencrypt-issuer + solverConfig: | + dns01: + provider: cloud-dns-provider + ``` - 1. Ensure that the file was updated successfully: + 1. Ensure that the file was updated successfully: - ```shell - kubectl get configmap config-certmanager --namespace knative-serving --output yaml - ``` + ```shell + kubectl get configmap config-certmanager --namespace knative-serving --output yaml + ``` 1. Update the [`config-network` ConfigMap](https://github.com/knative/serving/blob/master/config/config-network.yaml) in the `knative-serving` namespace to enable `autoTLS`and specify how HTTP requests are handled: - 1. Run the following command to edit your `config-network` ConfigMap: + 1. Run the following command to edit your `config-network` ConfigMap: - ```shell - kubectl edit configmap config-network --namespace knative-serving - ``` + ```shell + kubectl edit configmap config-network --namespace knative-serving + ``` - 1. Add the `autoTLS: Enabled` attribute under the `data` section: + 1. Add the `autoTLS: Enabled` attribute under the `data` section: - ```shell - ... - data: - ... - autoTLS: Enabled - ... - ``` + ```shell + ... + data: + ... + autoTLS: Enabled + ... + ``` - Example: + Example: - ```shell - apiVersion: v1 - kind: ConfigMap - metadata: - name: config-network - namespace: knative-serving - data: - ... - autoTLS: Enabled - ... - ``` + ```shell + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-network + namespace: knative-serving + data: + ... + autoTLS: Enabled + ... + ``` - 1. Configure how HTTP and HTTPS requests are handled in the - [`httpProtocol`](https://github.com/knative/serving/blob/master/config/config-network.yaml#L110) - attribute. + 1. Configure how HTTP and HTTPS requests are handled in the + [`httpProtocol`](https://github.com/knative/serving/blob/master/config/config-network.yaml#L110) + attribute. - By default, Knative ingress is configured to serve HTTP traffic - (`httpProtocol: Enabled`). Now that your cluster is configured to use - TLS certificates and handle HTTPS traffic, you can specify whether or not - any HTTP traffic is allowed. + By default, Knative ingress is configured to serve HTTP traffic + (`httpProtocol: Enabled`). Now that your cluster is configured to use TLS + certificates and handle HTTPS traffic, you can specify whether or not any + HTTP traffic is allowed. - Supported `httpProtocol` values: + Supported `httpProtocol` values: - - `Enabled`: Serve HTTP traffic. - - `Disabled`: Rejects all HTTP traffic. - - `Redirected`: Responds to HTTP request with a `302` redirect to ask - the clients to use HTTPS. + - `Enabled`: Serve HTTP traffic. + - `Disabled`: Rejects all HTTP traffic. + - `Redirected`: Responds to HTTP request with a `302` redirect to ask the + clients to use HTTPS. ```shell @@ -244,12 +248,6 @@ To enable Knative to automatically provision TLS certificates: kubectl get configmap config-network --namespace knative-serving --output yaml ``` - 1. Ensure that the file was updated successfully: - - ```shell - kubectl get configmap config-network --namespace knative-serving --output yaml - ``` - Congratulations! Knative is now configured to obtain and renew TLS certificates. When your TLS certificate is active on your cluster, your Knative services will be able to handle HTTPS traffic.