From 8cc1e93c5673dc18b8cc473b35656ad41c0d5636 Mon Sep 17 00:00:00 2001 From: Vincent Hou Date: Thu, 9 Jan 2020 10:58:42 -0500 Subject: [PATCH 1/9] Update the instruction on how to use cluster local gateway --- docs/install/installing-istio.md | 72 ++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/docs/install/installing-istio.md b/docs/install/installing-istio.md index 1ce26ca10d8..1abf99addbf 100644 --- a/docs/install/installing-istio.md +++ b/docs/install/installing-istio.md @@ -141,6 +141,78 @@ spec: EOF ``` +**Note:** This method is only for development purposes. The production readiness of the above +installation method is not ensured. For a production-ready installation, see the `helm` installation method above. + +If you follow either of the above steps, your service and deployment for the local gateway are both named `cluster-local-gateway`, +and you do not need to update gateway configmap `config-istio` under `knative-serving` namespace, because Knative Serving +can by default use the local gateway with the name `cluster-local-gateway`. + +However, if you create custom service and deployment for local gateway with a name other than `cluster-local-gateway`, you +need to update gateway configmap `config-istio` under `knative-serving` namespace. Run the following command: + +```shell +kubectl edit configmap config-istio -n knative-serving +``` + +Replace the `local-gateway.knative-serving.cluster-local-gateway` field with the custom service. If you name both +of the service and deployment after `custom-local-gateway` under the namespace `istio-system`, it should be updated to: + +``` +custom-local-gateway.istio-system.svc.cluster.local +``` + +### Verifying your Istio install + +View the status of your Istio installation to make sure the install was +successful. It might take a few seconds, so rerun the following command until +all of the pods show a `STATUS` of `Running` or `Completed`: + +```bash +kubectl get pods --namespace istio-system +``` + +> Tip: You can append the `--watch` flag to the `kubectl get` commands to view +> the pod status in realtime. You use `CTRL + C` to exit watch mode. + +### Configuring DNS + +Knative dispatches to different services based on their hostname, so it greatly +simplifies things to have DNS properly configured. For this, we must look up the +external IP address that Istio received. This can be done with the following +command: + +``` +$ kubectl get svc -nistio-system +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +cluster-local-gateway ClusterIP 10.0.2.216 15020/TCP,80/TCP,443/TCP 2m14s +istio-ingressgateway LoadBalancer 10.0.2.24 34.83.80.117 15020:32206/TCP,80:30742/TCP,443:30996/TCP 2m14s +istio-pilot ClusterIP 10.0.3.27 15010/TCP,15011/TCP,8080/TCP,15014/TCP 2m14s +``` + +This external IP can be used with your DNS provider with a wildcard `A` record; +however, for a basic functioning DNS setup (not suitable for production!) this +external IP address can be used with `xip.io` in the `config-domain` ConfigMap +in `knative-serving`. You can edit this with the following command: + +``` +kubectl edit cm config-domain --namespace knative-serving +``` + +Given the external IP above, change the content to: + +``` +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-domain + namespace: knative-serving +data: + # xip.io is a "magic" DNS provider, which resolves all DNS lookups for: + # *.{ip}.xip.io to {ip}. + 34.83.80.117.xip.io: "" +``` + ## Istio resources - For the official Istio installation guide, see the From 4828bf37180d7676cdcf342ce20533f4dd6aa5a7 Mon Sep 17 00:00:00 2001 From: Vincent Hou Date: Wed, 26 Feb 2020 11:04:57 -0500 Subject: [PATCH 2/9] Update the explanation of updating local gateway based on comments --- docs/install/installing-istio.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/install/installing-istio.md b/docs/install/installing-istio.md index 1abf99addbf..2451fe8689a 100644 --- a/docs/install/installing-istio.md +++ b/docs/install/installing-istio.md @@ -144,18 +144,22 @@ EOF **Note:** This method is only for development purposes. The production readiness of the above installation method is not ensured. For a production-ready installation, see the `helm` installation method above. -If you follow either of the above steps, your service and deployment for the local gateway are both named `cluster-local-gateway`, -and you do not need to update gateway configmap `config-istio` under `knative-serving` namespace, because Knative Serving -can by default use the local gateway with the name `cluster-local-gateway`. +After you install the cluster local gateway, your service and deployment for the local gateway are both named `cluster-local-gateway`. +You do not need to update the `config-istio` configmap under `knative-serving` namespace, because Knative Serving can use +this local gateway cluster-local-gateway by default. + +### Updating the `config-istio` configmap to use a non-default local gateway However, if you create custom service and deployment for local gateway with a name other than `cluster-local-gateway`, you -need to update gateway configmap `config-istio` under `knative-serving` namespace. Run the following command: +need to update gateway configmap `config-istio` under `knative-serving` namespace. + +1. Run the following command: ```shell kubectl edit configmap config-istio -n knative-serving ``` -Replace the `local-gateway.knative-serving.cluster-local-gateway` field with the custom service. If you name both +2. Replace the `local-gateway.knative-serving.cluster-local-gateway` field with the custom service. If you name both of the service and deployment after `custom-local-gateway` under the namespace `istio-system`, it should be updated to: ``` From 9dd4491f6dd96c7fb6561730ca64ff5684f2e950 Mon Sep 17 00:00:00 2001 From: Vincent Hou Date: Fri, 28 Feb 2020 13:35:20 -0500 Subject: [PATCH 3/9] Fix the minor issue --- docs/install/installing-istio.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install/installing-istio.md b/docs/install/installing-istio.md index 2451fe8689a..25edd91696e 100644 --- a/docs/install/installing-istio.md +++ b/docs/install/installing-istio.md @@ -150,7 +150,7 @@ this local gateway cluster-local-gateway by default. ### Updating the `config-istio` configmap to use a non-default local gateway -However, if you create custom service and deployment for local gateway with a name other than `cluster-local-gateway`, you +If you create custom service and deployment for local gateway with a name other than `cluster-local-gateway`, you need to update gateway configmap `config-istio` under `knative-serving` namespace. 1. Run the following command: From f7475690049ff318034bbfdc616dba907df27fa8 Mon Sep 17 00:00:00 2001 From: Vincent Hou Date: Mon, 2 Mar 2020 16:21:15 -0500 Subject: [PATCH 4/9] Add the doc on updating Knative gateway --- docs/install/installing-istio.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/install/installing-istio.md b/docs/install/installing-istio.md index 25edd91696e..30576081d35 100644 --- a/docs/install/installing-istio.md +++ b/docs/install/installing-istio.md @@ -150,6 +150,8 @@ this local gateway cluster-local-gateway by default. ### Updating the `config-istio` configmap to use a non-default local gateway +#### Update Gateway Configmap + If you create custom service and deployment for local gateway with a name other than `cluster-local-gateway`, you need to update gateway configmap `config-istio` under `knative-serving` namespace. @@ -166,6 +168,30 @@ of the service and deployment after `custom-local-gateway` under the namespace ` custom-local-gateway.istio-system.svc.cluster.local ``` +#### Update Knative Gateway + +If both of the custom service and deployment are labeled with `custom: custom-local-gateway`, not the default +`istio: cluster-local-gateway`, you need to update gateway instance `cluster-local-gateway` in `knative-serving` namespace: + +```shell +kubectl edit gateway cluster-local-gateway -n knative-serving +``` + +Replace the label selector with the label of your service: + +``` +istio: cluster-local-gateway +``` + +For the service above, it should be updated to: + +``` +custom: custom-local-gateway +``` + +If there is a change in service ports (compared with that of +`cluster-local-gateway`), update the port info in the gateway accordingly. + ### Verifying your Istio install View the status of your Istio installation to make sure the install was From ea92f7b84f8f9ee6b30b25beb170de3bc5fc9e29 Mon Sep 17 00:00:00 2001 From: Vincent Hou Date: Wed, 18 Mar 2020 18:38:10 -0400 Subject: [PATCH 5/9] Fixed this PR based on latest comments --- docs/install/installing-istio.md | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/install/installing-istio.md b/docs/install/installing-istio.md index 30576081d35..a9335b109e0 100644 --- a/docs/install/installing-istio.md +++ b/docs/install/installing-istio.md @@ -141,36 +141,32 @@ spec: EOF ``` -**Note:** This method is only for development purposes. The production readiness of the above -installation method is not ensured. For a production-ready installation, see the `helm` installation method above. +__Note:__ This installation method is not production ready and is for development purposes only. For a more stable method, +use Helm. For more information about the Helm installation method, see [Installing Helm](https://helm.sh/docs/intro/install/). After you install the cluster local gateway, your service and deployment for the local gateway are both named `cluster-local-gateway`. -You do not need to update the `config-istio` configmap under `knative-serving` namespace, because Knative Serving can use -this local gateway cluster-local-gateway by default. +You do not need to update the `config-istio` configmap under the `knative-serving` namespace, because Knative Serving can use +the local gateway cluster-local-gateway by default. ### Updating the `config-istio` configmap to use a non-default local gateway -#### Update Gateway Configmap +If you create a custom service and deployment for local gateway with a name other than `cluster-local-gateway`, you +need to update gateway configmap `config-istio` under the `knative-serving` namespace. -If you create custom service and deployment for local gateway with a name other than `cluster-local-gateway`, you -need to update gateway configmap `config-istio` under `knative-serving` namespace. - -1. Run the following command: +1. Edit the 1config-istio1 configmap: ```shell kubectl edit configmap config-istio -n knative-serving ``` 2. Replace the `local-gateway.knative-serving.cluster-local-gateway` field with the custom service. If you name both -of the service and deployment after `custom-local-gateway` under the namespace `istio-system`, it should be updated to: +the service and deployment `custom-local-gateway` under the namespace `istio-system`, it should be updated to: ``` custom-local-gateway.istio-system.svc.cluster.local ``` -#### Update Knative Gateway - -If both of the custom service and deployment are labeled with `custom: custom-local-gateway`, not the default +If both the custom service and deployment are labeled with `custom: custom-local-gateway`, not the default `istio: cluster-local-gateway`, you need to update gateway instance `cluster-local-gateway` in `knative-serving` namespace: ```shell @@ -189,7 +185,7 @@ For the service above, it should be updated to: custom: custom-local-gateway ``` -If there is a change in service ports (compared with that of +If there is a change in service ports (compared to that of `cluster-local-gateway`), update the port info in the gateway accordingly. ### Verifying your Istio install From 7f012089a069760fd67080075408363dc30e7ec9 Mon Sep 17 00:00:00 2001 From: Vincent Hou Date: Thu, 19 Mar 2020 13:16:53 -0400 Subject: [PATCH 6/9] Change the desciption for DNS configuration --- docs/install/installing-istio.md | 11 +++++------ docs/serving/setting-up-custom-ingress-gateway.md | 2 +- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/install/installing-istio.md b/docs/install/installing-istio.md index a9335b109e0..447d2dbf75a 100644 --- a/docs/install/installing-istio.md +++ b/docs/install/installing-istio.md @@ -141,7 +141,7 @@ spec: EOF ``` -__Note:__ This installation method is not production ready and is for development purposes only. For a more stable method, +**Note:** This installation method is not production ready and is for development purposes only. For a more stable method, use Helm. For more information about the Helm installation method, see [Installing Helm](https://helm.sh/docs/intro/install/). After you install the cluster local gateway, your service and deployment for the local gateway are both named `cluster-local-gateway`. @@ -167,7 +167,7 @@ custom-local-gateway.istio-system.svc.cluster.local ``` If both the custom service and deployment are labeled with `custom: custom-local-gateway`, not the default -`istio: cluster-local-gateway`, you need to update gateway instance `cluster-local-gateway` in `knative-serving` namespace: +`istio: cluster-local-gateway`, you need to update gateway instance `cluster-local-gateway` in the `knative-serving` namespace: ```shell kubectl edit gateway cluster-local-gateway -n knative-serving @@ -203,10 +203,9 @@ kubectl get pods --namespace istio-system ### Configuring DNS -Knative dispatches to different services based on their hostname, so it greatly -simplifies things to have DNS properly configured. For this, we must look up the -external IP address that Istio received. This can be done with the following -command: +You must configure your DNS settings to allow Knative to dispatch services based on +their hostname. To do this, you must look up the external IP address received by Istio +by entering the following command: ``` $ kubectl get svc -nistio-system diff --git a/docs/serving/setting-up-custom-ingress-gateway.md b/docs/serving/setting-up-custom-ingress-gateway.md index 2e040a67a42..c51059b1c9c 100644 --- a/docs/serving/setting-up-custom-ingress-gateway.md +++ b/docs/serving/setting-up-custom-ingress-gateway.md @@ -7,7 +7,7 @@ type: "docs" Knative uses a shared ingress Gateway to serve all incoming traffic within Knative service mesh, which is the `knative-ingress-gateway` Gateway under -`knative-serving` namespace. By default, we use Istio gateway service +the `knative-serving` namespace. By default, we use Istio gateway service `istio-ingressgateway` under `istio-system` namespace as its underlying service. You can replace the service with that of your own as follows. From a24c63ba317c8d7c58d00f49ad3b634c25f9e1e7 Mon Sep 17 00:00:00 2001 From: Vincent Hou Date: Thu, 2 Apr 2020 13:26:07 -0400 Subject: [PATCH 7/9] Fix broken links and remove vendor specific section --- docs/install/installing-istio.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/install/installing-istio.md b/docs/install/installing-istio.md index 447d2dbf75a..fe4562ea598 100644 --- a/docs/install/installing-istio.md +++ b/docs/install/installing-istio.md @@ -264,3 +264,4 @@ See the [Uninstall Istio](https://istio.io/docs/setup/install/istioctl/#uninstal https://istio.io/docs/setup/kubernetes/additional-setup/sidecar-injection/#automatic-sidecar-injection [3]: https://istio.io/docs/concepts/security/#mutual-tls-authentication [4]: https://istio.io/docs/tasks/security/authz-http/ +[4]: https://istio.io/docs/concepts/security/#mutual-tls-authentication From f1cf6075e2b7a87cc44b59b6fa69b48323bc2cf8 Mon Sep 17 00:00:00 2001 From: Vincent Hou Date: Fri, 12 Jun 2020 10:56:46 -0400 Subject: [PATCH 8/9] Refactoring the doc --- docs/install/installing-istio.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/install/installing-istio.md b/docs/install/installing-istio.md index fe4562ea598..a65a8f69c9c 100644 --- a/docs/install/installing-istio.md +++ b/docs/install/installing-istio.md @@ -141,9 +141,6 @@ spec: EOF ``` -**Note:** This installation method is not production ready and is for development purposes only. For a more stable method, -use Helm. For more information about the Helm installation method, see [Installing Helm](https://helm.sh/docs/intro/install/). - After you install the cluster local gateway, your service and deployment for the local gateway are both named `cluster-local-gateway`. You do not need to update the `config-istio` configmap under the `knative-serving` namespace, because Knative Serving can use the local gateway cluster-local-gateway by default. @@ -203,9 +200,10 @@ kubectl get pods --namespace istio-system ### Configuring DNS -You must configure your DNS settings to allow Knative to dispatch services based on -their hostname. To do this, you must look up the external IP address received by Istio -by entering the following command: +Knative dispatches to different services based on their hostname, so it greatly +simplifies things to have DNS properly configured. For this, we must look up the +external IP address that Istio received. This can be done with the following +command: ``` $ kubectl get svc -nistio-system @@ -264,4 +262,3 @@ See the [Uninstall Istio](https://istio.io/docs/setup/install/istioctl/#uninstal https://istio.io/docs/setup/kubernetes/additional-setup/sidecar-injection/#automatic-sidecar-injection [3]: https://istio.io/docs/concepts/security/#mutual-tls-authentication [4]: https://istio.io/docs/tasks/security/authz-http/ -[4]: https://istio.io/docs/concepts/security/#mutual-tls-authentication From 1433df32f5f055b5b784902196c0d8d5835c5e72 Mon Sep 17 00:00:00 2001 From: Vincent Hou Date: Mon, 20 Jul 2020 11:31:47 -0400 Subject: [PATCH 9/9] Change the PR based on comments --- docs/install/installing-istio.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/docs/install/installing-istio.md b/docs/install/installing-istio.md index a65a8f69c9c..eceb43ddfda 100644 --- a/docs/install/installing-istio.md +++ b/docs/install/installing-istio.md @@ -142,29 +142,27 @@ EOF ``` After you install the cluster local gateway, your service and deployment for the local gateway are both named `cluster-local-gateway`. -You do not need to update the `config-istio` configmap under the `knative-serving` namespace, because Knative Serving can use -the local gateway cluster-local-gateway by default. ### Updating the `config-istio` configmap to use a non-default local gateway If you create a custom service and deployment for local gateway with a name other than `cluster-local-gateway`, you need to update gateway configmap `config-istio` under the `knative-serving` namespace. -1. Edit the 1config-istio1 configmap: +1. Edit the `config-istio` configmap: ```shell kubectl edit configmap config-istio -n knative-serving ``` -2. Replace the `local-gateway.knative-serving.cluster-local-gateway` field with the custom service. If you name both +2. Replace the `local-gateway.knative-serving.cluster-local-gateway` field with the custom service. As an example, if you name both the service and deployment `custom-local-gateway` under the namespace `istio-system`, it should be updated to: ``` custom-local-gateway.istio-system.svc.cluster.local ``` -If both the custom service and deployment are labeled with `custom: custom-local-gateway`, not the default -`istio: cluster-local-gateway`, you need to update gateway instance `cluster-local-gateway` in the `knative-serving` namespace: +As an example, if both the custom service and deployment are labeled with `custom: custom-local-gateway`, not the default +`istio: cluster-local-gateway`, you must update gateway instance `cluster-local-gateway` in the `knative-serving` namespace: ```shell kubectl edit gateway cluster-local-gateway -n knative-serving @@ -200,10 +198,9 @@ kubectl get pods --namespace istio-system ### Configuring DNS -Knative dispatches to different services based on their hostname, so it greatly -simplifies things to have DNS properly configured. For this, we must look up the -external IP address that Istio received. This can be done with the following -command: +Knative dispatches to different services based on their hostname, so it is recommended to have DNS properly configured. + +To do this, begin by looking up the external IP address that Istio received: ``` $ kubectl get svc -nistio-system @@ -213,10 +210,10 @@ istio-ingressgateway LoadBalancer 10.0.2.24 34.83.80.117 15020:32206/T istio-pilot ClusterIP 10.0.3.27 15010/TCP,15011/TCP,8080/TCP,15014/TCP 2m14s ``` -This external IP can be used with your DNS provider with a wildcard `A` record; -however, for a basic functioning DNS setup (not suitable for production!) this -external IP address can be used with `xip.io` in the `config-domain` ConfigMap -in `knative-serving`. You can edit this with the following command: +This external IP can be used with your DNS provider with a wildcard `A` record. However, for a basic non-production set +up, this external IP address can be used with `xip.io` in the `config-domain` ConfigMap in `knative-serving`. + +You can edit this by using the following command: ``` kubectl edit cm config-domain --namespace knative-serving