diff --git a/docs/install/knative-with-operators.md b/docs/install/knative-with-operators.md index 894fc338de3..4ad8319f200 100644 --- a/docs/install/knative-with-operators.md +++ b/docs/install/knative-with-operators.md @@ -207,6 +207,358 @@ NAME VERSION READY REASON knative-serving True ``` +### Installing the Knative Serving component with different network layers + +Knative Operator can configure Knative Serving component with different network layer options. Istio is the default network +layer, if the ingress is not specified in the Knative Serving CR. Click on each tab below to see how you can configure +Knative Serving with different ingresses: + + {{< tabs name="serving_networking" default="Ambassador" >}} + {{% tab name="Ambassador" %}} + +{{% feature-state version="v0.8" state="alpha" %}} + +The following commands install Ambassador and enable its Knative integration. + +1. Create a namespace to install Ambassador in: + + ```bash + kubectl create namespace ambassador + ``` + +1. Install Ambassador: + + ```bash + kubectl apply --namespace ambassador \ + --filename https://getambassador.io/yaml/ambassador/ambassador-crds.yaml \ + --filename https://getambassador.io/yaml/ambassador/ambassador-rbac.yaml \ + --filename https://getambassador.io/yaml/ambassador/ambassador-service.yaml + ``` + +1. Give Ambassador the required permissions: + + ```bash + kubectl patch clusterrolebinding ambassador -p '{"subjects":[{"kind": "ServiceAccount", "name": "ambassador", "namespace": "ambassador"}]}' + ``` + +1. Enable Knative support in Ambassador: + + ```bash + kubectl set env --namespace ambassador deployments/ambassador AMBASSADOR_KNATIVE_SUPPORT=true + ``` + +1. To configure Knative Serving to use Ambassador, apply the content of the Serving CR as below: + + ```bash + cat <<-EOF | kubectl apply -f - + apiVersion: operator.knative.dev/v1alpha1 + kind: KnativeServing + metadata: + name: knative-serving + namespace: knative-serving + spec: + config: + network: + ingress.class: "ambassador.ingress.networking.knative.dev" + EOF + ``` + +1. Fetch the External IP or CNAME: + + ```bash + kubectl --namespace ambassador get service ambassador + ``` + + Save this for configuring DNS below. + +{{< /tab >}} + +{{% tab name="Contour" %}} + +{{% feature-state version="v0.18" state="stable" %}} + +The following commands install Contour and enable its Knative integration. + +1. Install a properly configured Contour: + + ```bash + kubectl apply --filename {{< artifact repo="net-contour" file="contour.yaml" >}} + ``` + +1. Install the Knative Contour controller: + + ```bash + kubectl apply --filename {{< artifact repo="net-contour" file="net-contour.yaml" >}} + ``` + +1. To configure Knative Serving to use Contour, apply the content of the Serving CR as below: + + ```bash + cat <<-EOF | kubectl apply -f - + apiVersion: operator.knative.dev/v1alpha1 + kind: KnativeServing + metadata: + name: knative-serving + namespace: knative-serving + spec: + config: + network: + ingress.class: "contour.ingress.networking.knative.dev" + EOF + ``` + +1. Fetch the External IP or CNAME: + + ```bash + kubectl --namespace contour-external get service envoy + ``` + + Save this for configuring DNS below. + +{{< /tab >}} + +{{% tab name="Gloo" %}} + +{{% feature-state version="v0.8" state="alpha" %}} + +_For a detailed guide on Gloo integration, see +[Installing Gloo for Knative](https://docs.solo.io/gloo/latest/installation/knative/) +in the Gloo documentation._ + +The following commands install Gloo and enable its Knative integration. + +1. Make sure `glooctl` is installed (version 1.3.x and higher recommended): + + ```bash + glooctl version + ``` + + If it is not installed, you can install the latest version using: + + ```bash + curl -sL https://run.solo.io/gloo/install | sh + export PATH=$HOME/.gloo/bin:$PATH + ``` + + Or following the + [Gloo CLI install instructions](https://docs.solo.io/gloo/latest/installation/knative/#install-command-line-tool-cli). + +1. Install Gloo and the Knative integration: + + ```bash + glooctl install knative --install-knative=false + ``` + +1. To configure Knative Serving to use Gloo, apply the content of the Serving CR as below: + + ```bash + cat <<-EOF | kubectl apply -f - + apiVersion: operator.knative.dev/v1alpha1 + kind: KnativeServing + metadata: + name: knative-serving + namespace: knative-serving + spec: + ingress: + gloo: + enabled: true + EOF + ``` + +1. Fetch the External IP or CNAME: + + ```bash + glooctl proxy url --name knative-external-proxy + ``` + + Save this for configuring DNS below. + +{{< /tab >}} + +{{% tab name="Kong" %}} + +{{% feature-state version="v0.13" state="" %}} + +The following commands install Kong and enable its Knative integration. + +1. Install Kong Ingress Controller: + + ```bash + kubectl apply --filename https://raw.githubusercontent.com/Kong/kubernetes-ingress-controller/0.9.x/deploy/single/all-in-one-dbless.yaml + ``` + +1. To configure Knative Serving to use Kong, apply the content of the Serving CR as below: + + ```bash + cat <<-EOF | kubectl apply -f - + apiVersion: operator.knative.dev/v1alpha1 + kind: KnativeServing + metadata: + name: knative-serving + namespace: knative-serving + spec: + config: + network: + ingress.class: "kong" + EOF + ``` + +1. Fetch the External IP or CNAME: + + ```bash + kubectl --namespace kong get service kong-proxy + ``` + + Save this for configuring DNS below. + +{{< /tab >}} + +{{% tab name="Kourier" %}} + +{{% feature-state version="v0.17" state="beta" %}} + +The following commands install Kourier and enable its Knative integration. + +1. Install the Knative Kourier controller: + + ```bash + kubectl apply --filename {{< artifact repo="net-kourier" file="kourier.yaml" >}} + ``` + +1. To configure Knative Serving to use Kourier, apply the content of the Serving CR as below: + + ```bash + cat <<-EOF | kubectl apply -f - + apiVersion: operator.knative.dev/v1alpha1 + kind: KnativeServing + metadata: + name: knative-serving + namespace: knative-serving + spec: + config: + network: + ingress.class: "kourier.ingress.networking.knative.dev" + EOF + ``` + +1. Fetch the External IP or CNAME: + + ```bash + kubectl --namespace knative-serving get service kourier + ``` + + Save this for configuring DNS below. + +{{< /tab >}} {{< /tabs >}} + +1. Configure DNS + + + + {{< tabs name="serving_dns" >}} {{% tab name="Magic DNS (xip.io)" %}} We ship + a simple Kubernetes Job called "default domain" that will (see caveats) + configure Knative Serving to use xip.io as the + default DNS suffix. + +```bash +kubectl apply --filename {{< artifact repo="serving" file="serving-default-domain.yaml" >}} +``` + +**Caveat**: This will only work if the cluster LoadBalancer service exposes an +IPv4 address or hostname, so it will not work with IPv6 clusters or local setups +like Minikube. For these, see "Real DNS" or "Temporary DNS". {{< /tab >}} + +{{% tab name="Real DNS" %}} To configure DNS for Knative, take the External IP +or CNAME from setting up networking, and configure it with your DNS provider as +follows: + +- If the networking layer produced an External IP address, then configure a + wildcard `A` record for the domain: + + ``` + # Here knative.example.com is the domain suffix for your cluster + *.knative.example.com == A 35.233.41.212 + ``` + +- If the networking layer produced a CNAME, then configure a CNAME record for + the domain: + + ``` + # Here knative.example.com is the domain suffix for your cluster + *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com + ``` + +Once your DNS provider has been configured, add the following section into your existing Serving CR, and apply it: + +```bash +# Replace knative.example.com with your domain suffix +apiVersion: operator.knative.dev/v1alpha1 +kind: KnativeServing +metadata: + name: knative-serving + namespace: knative-serving +spec: + config: + domain: + "knative.example.com": "" + ... +``` + +{{< /tab >}} + +{{% tab name="Temporary DNS" %}} If you are using `curl` to access the sample +applications, or your own Knative app, and are unable to use the "Magic DNS +(xip.io)" or "Real DNS" methods, there is a temporary approach. This is useful +for those who wish to evaluate Knative without altering their DNS configuration, +as per the "Real DNS" method, or cannot use the "Magic DNS" method due to using, +for example, minikube locally or IPv6 clusters. + +To access your application using `curl` using this method: + +1. After starting your application, get the URL of your application: + + ```bash + kubectl get ksvc + ``` + + The output should be similar to: + + ```bash + NAME URL LATESTCREATED LATESTREADY READY REASON + helloworld-go http://helloworld-go.default.example.com helloworld-go-vqjlf helloworld-go-vqjlf True + ``` + +1. Instruct `curl` to connect to the External IP or CNAME defined by the + networking layer in section 3 above, and use the `-H "Host:"` command-line + option to specify the Knative application's host name. For example, if the + networking layer defines your External IP and port to be + `http://192.168.39.228:32198` and you wish to access the above + `helloworld-go` application, use: + + ```bash + curl -H "Host: helloworld-go.default.example.com" http://192.168.39.228:32198 + ``` + + In the case of the provided `helloworld-go` sample application, using the default + configuration, the output should be: + + ``` + Hello Go Sample v1! + ``` + +Refer to the "Real DNS" method for a permanent solution. + +{{< /tab >}} + +{{< /tabs >}} + +1. Monitor the Knative components until all of the components show a `STATUS` of + `Running` or `Completed`: + + ```bash + kubectl get pods --namespace knative-serving + ``` + ### Installing the Knative Eventing component 1. Create and apply the Knative Eventing CR: