diff --git a/_topic_map.yml b/_topic_map.yml index 7a66154fc7ca..485ffd6a87ac 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -2680,6 +2680,12 @@ Topics: File: upgrading-serverless - Name: Removing OpenShift Serverless File: removing-openshift-serverless + # Ingress options + - Name: Integrating Service Mesh with OpenShift Serverless + File: serverless-ossm-setup + # Eventing + - Name: Creating Knative Eventing components in the Administrator perspective + File: serverless-cluster-admin-eventing # Serving - Name: Creating Knative Serving components in the Administrator perspective File: serverless-cluster-admin-serving @@ -2715,6 +2721,17 @@ Topics: # Tracing - Name: Tracing requests using Jaeger File: serverless-tracing + # JWT using kourier + - Name: Configuring JSON Web Token authentication for Knative services + File: serverless-ossm-with-kourier-jwt + # Custom domains + - Name: Configuring a custom domain for a Knative service + File: serverless-custom-domains + - Name: Configuring TLS for a custom domain + File: serverless-ossm-tls-with-kourier + # Routes + - Name: Configuring routes for Knative services + File: serverless-configuring-routes # # Knative Eventing - Name: Knative Eventing @@ -2789,24 +2806,6 @@ Topics: File: serverless-developing-quarkus-functions - Name: Functions development reference guide File: serverless-functions-reference-guide -# -# Networking -- Name: Networking - Dir: networking - Topics: - - Name: Mapping a custom domain name to a Knative service - File: serverless-domain-mapping - - Name: Configuring routes for Knative services - File: serverless-configuring-routes - - Name: Using Service Mesh with OpenShift Serverless - File: serverless-ossm - - Name: Using JSON Web Token authentication with Service Mesh and OpenShift Serverless - File: serverless-ossm-jwt - - Name: Using custom domains for Knative services with Service Mesh - File: serverless-ossm-custom-domains - - Name: Configuring TLS for a custom domain using Service Mesh - File: serverless-ossm-tls -# # Integrations - Name: Integrations Dir: integrations diff --git a/modules/serverless-config-replicas.adoc b/modules/serverless-config-replicas.adoc index 96610f7c6dce..6df2aa500bdd 100644 --- a/modules/serverless-config-replicas.adoc +++ b/modules/serverless-config-replicas.adoc @@ -3,10 +3,11 @@ High availability (HA) functionality is available by default on {ServerlessProductName} for the `autoscaler-hpa`, `controller`, `activator`, `kourier-control`, and `kourier-gateway` controllers. These components are configured with two replicas by default. -You modify the number of replicas that are created per controller by changing the configuration of the `KnativeServing.spec.highAvailability` spec in the `KnativeServing` custom resource definition (CRD). +You can modify the number of replicas that are created per controller by changing the configuration of the `high-availability` spec in the `KnativeServing` custom resource definition (CRD). .Prerequisites -* You have access to a {product-title} account with cluster administrator access. + +* You have access to an {product-title} cluster with cluster administrator permissions. * The {ServerlessOperatorName} and Knative Serving are installed on your cluster. * You have logged into the web console. @@ -26,7 +27,7 @@ image::serving-tab-created.png[Knative Serving tab] + image::serving-YAML-HA.png[Knative Serving YAML] + -. Edit the custom resource definition YAML: +. Modify the number of replicas in the `KnativeServing` CRD: + .Example YAML [source,yaml] diff --git a/modules/serverless-create-domain-mapping.adoc b/modules/serverless-create-domain-mapping.adoc index 375f2ffebe1c..632246d0421c 100644 --- a/modules/serverless-create-domain-mapping.adoc +++ b/modules/serverless-create-domain-mapping.adoc @@ -10,7 +10,7 @@ To map a custom domain name to a custom resource (CR), you must create a `Domain + [NOTE] ==== -Your custom domain must point to the DNS of the {product-title} cluster. +Your custom domain must point to the IP address of the {product-title} cluster. ==== .Procedure diff --git a/modules/serverless-openshift-routes.adoc b/modules/serverless-openshift-routes.adoc index b192f615157a..71856c798bdf 100644 --- a/modules/serverless-openshift-routes.adoc +++ b/modules/serverless-openshift-routes.adoc @@ -1,6 +1,3 @@ -// Module included in the following assemblies: -// * serverless/networking/serverless-configuring-routes.adoc - [id="serverless-openshift-routes_{context}"] = Configuring {product-title} routes for Knative services @@ -10,11 +7,17 @@ If you want to configure a Knative service to use your TLS certificate on {produ * The {ServerlessOperatorName} and Knative Serving component must be installed on your {product-title} cluster. +[NOTE] +==== +You must modify the replaceable values in the example commands for the following procedure. +==== + .Procedure . Create a Knative service that includes the `serving.knative.openshift.io/disableRoute=true` annotation: +.. Optional. Create a Knative service resource: + -.Example YAML +.Example resource [source,yaml] ---- apiVersion: serving.knative.dev/v1 @@ -29,11 +32,18 @@ spec: containers: - image: ---- +.. Apply the `Service` resource: ++ +[source,terminal] +---- +$ oc apply -f +---- +.. Optional. Create a Knative service by using the `kn service create` command: + .Example `kn` command [source,terminal] ---- -$ kn service create hello-example \ +$ kn service create \ --image=gcr.io/knative-samples/helloworld-go \ --annotation serving.knative.openshift.io/disableRoute=true ---- @@ -43,17 +53,20 @@ $ kn service create hello-example \ .Example command [source,terminal] ---- -$ oc get routes.route.openshift.io -l serving.knative.openshift.io/ingressName=$KSERVICE_NAME -l serving.knative.openshift.io/ingressNamespace=$KSERVICE_NAMESPACE -n knative-serving-ingress +$ $ oc get routes.route.openshift.io \ + -l serving.knative.openshift.io/ingressName=$KSERVICE_NAME \ + -l serving.knative.openshift.io/ingressNamespace=$KSERVICE_NAMESPACE \ + -n knative-serving-ingress ---- + -You should see the following output: +You will see the following output: + [source,terminal] ---- No resources found in knative-serving-ingress namespace. ---- -. Create a `Route` object in the `knative-serving-ingress` namespace by copying the following sample YAML and modifying the replaceable values: +. Create a `Route` resource in the `knative-serving-ingress` namespace: + [source,yaml] ---- @@ -94,3 +107,9 @@ spec: <3> The namespace for the {product-title} route. This must be `knative-serving-ingress`. <4> The hostname for external access. You can set this to `-.`. <5> The certificates you want to use. Currently, only `edge` termination is supported. +. Apply the `Route` resource: ++ +[source,terminal] +---- +$ oc apply -f +---- diff --git a/modules/serverless-service-mesh-enable-sidecar-injection.adoc b/modules/serverless-ossm-enable-sidecar-injection-with-kourier.adoc similarity index 52% rename from modules/serverless-service-mesh-enable-sidecar-injection.adoc rename to modules/serverless-ossm-enable-sidecar-injection-with-kourier.adoc index 15f3086ead67..c3529a1178b9 100644 --- a/modules/serverless-service-mesh-enable-sidecar-injection.adoc +++ b/modules/serverless-ossm-enable-sidecar-injection-with-kourier.adoc @@ -1,43 +1,38 @@ -// Module included in the following assemblies: -// * serverless/networking/serverless-ossm.adoc -// * serverless/networking/serverless-ossm-jwt.adoc - -[id="serverless-enable-sidecar_{context}"] +[id="serverless-ossm-enable-sidecar-injection-with-kourier_{context}"] = Enabling sidecar injection for a Knative service You can add the `sidecar.istio.io/inject="true"` annotation to a Knative service to enable sidecar injection for that service. [IMPORTANT] ==== -Adding sidecar injection to pods in system namespaces such as `knative-serving` and `knative-serving-ingress` is not supported. +Adding sidecar injection to pods in system namespaces, such as `knative-serving` and `knative-serving-ingress`, is not supported when Kourier is enabled. + +If you require sidecar injection for pods in these namespaces, see the {ServerlessProductName} documentation on _Integrating {ProductShortName} with {ServerlessProductName} natively_. ==== +// Add an xref here once it's enabled for modules .Procedure -. Add the `sidecar.istio.io/inject="true"` annotation to the `Service` resource YAML file: +. Add the `sidecar.istio.io/inject="true"` annotation to your `Service` resource: + -.Example service YAML +.Example service [source,yaml] ---- apiVersion: serving.knative.dev/v1 kind: Service metadata: - name: event-display + name: spec: template: metadata: annotations: sidecar.istio.io/inject: "true" <1> sidecar.istio.io/rewriteAppHTTPProbers: "true" <2> - spec: - containers: - - image: quay.io/openshift-knative/knative-eventing-sources-event-display:latest - name: container +... ---- <1> Add the `sidecar.istio.io/inject="true"` annotation. <2> Optional: Add the `sidecar.istio.io/rewriteAppHTTPProbers="true"` annotation if you have enabled JSON Web Token (JWT) authentication. - -. Apply the `Service` resource YAML file: +. Apply your `Service` resource YAML file: + [source,terminal] ---- diff --git a/modules/serverless-ossm-setup-with-kourier.adoc b/modules/serverless-ossm-setup-with-kourier.adoc new file mode 100644 index 000000000000..a12dbfd06a0f --- /dev/null +++ b/modules/serverless-ossm-setup-with-kourier.adoc @@ -0,0 +1,70 @@ +[id="serverless-ossm-setup-with-kourier_{context}"] += Integrating {ProductShortName} with {ServerlessProductName} when Kourier is enabled + +.Prerequisites + +* You have installed the {ServerlessOperatorName} on your {product-title} cluster. +* You have installed {ProductName}. {ServerlessProductName} with {ProductShortName} and Kourier is supported for use with both {ProductName} versions 1.x and 2.x. +* You have installed Knative Serving. + +.Procedure + +. Add the namespaces that you would like to integrate with {ProductShortName} to the `ServiceMeshMemberRoll` object as members: ++ +[source,yaml] +---- +apiVersion: maistra.io/v1 +kind: ServiceMeshMemberRoll +metadata: + name: default + namespace: istio-system +spec: + members: + - <1> +---- +<1> A list of namespaces to be integrated with {ProductShortName}. +. Apply the `ServiceMeshMemberRoll` resource: ++ +[source,terminal] +---- +$ oc apply -f +---- +. Create a network policy that permits traffic flow from Knative system pods to Knative services: +.. Add the `serving.knative.openshift.io/system-namespace=true` label to the `knative-serving` namespace: ++ +[source,terminal] +---- +$ oc label namespace knative-serving serving.knative.openshift.io/system-namespace=true +---- +.. Add the `serving.knative.openshift.io/system-namespace=true` label to the `knative-serving-ingress` namespace: ++ +[source,terminal] +---- +$ oc label namespace knative-serving-ingress serving.knative.openshift.io/system-namespace=true +---- +.. For each namespace that you want to integrate with {ProductShortName}, create a `NetworkPolicy` resource: ++ +[source,yaml] +---- +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: allow-from-serving-system-namespace + namespace: <1> +spec: + ingress: + - from: + - namespaceSelector: + matchLabels: + serving.knative.openshift.io/system-namespace: "true" + podSelector: {} + policyTypes: + - Ingress +---- +<1> Add the namespace that you want to integrate with {ProductShortName}. +.. Apply the `NetworkPolicy` resource: ++ +[source,terminal] +---- +$ oc apply -f +---- diff --git a/modules/serverless-ossm-setup.adoc b/modules/serverless-ossm-setup.adoc index 8dd755135660..c2f760915ac3 100644 --- a/modules/serverless-ossm-setup.adoc +++ b/modules/serverless-ossm-setup.adoc @@ -1,12 +1,21 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm.adoc - [id="serverless-ossm-setup_{context}"] -= Using {ProductShortName} with {ServerlessProductName} += Integrating {ProductShortName} with {ServerlessProductName} + +You can integrate {ProductShortName} with {ServerlessProductName} without using Kourier by completing the following procedure. + +.Prerequisites + +* You have installed the {ServerlessOperatorName} on your {product-title} cluster. +* You have installed {ProductName}. {ServerlessProductName} with {ProductShortName} only is supported for use with {ProductName} version 2.0.5 or higher. + +[IMPORTANT] +==== +Do not install the Knative Serving component before completing the following procedures. There are additional steps required when creating the `KnativeServing` custom resource defintion (CRD) to integrate Knative Serving with {ProductShortName}, which are not covered in the general Knative Serving installation procedure of the _Administration guide_. +==== .Procedure +. Create a `ServiceMeshControlPlane` object in the `istio-system` namespace. If you want to use the mTLS functionality, this must be enabled for the `istio-system` namespace. . Add the namespaces that you would like to integrate with {ProductShortName} to the `ServiceMeshMemberRoll` object as members: + [source,yaml] @@ -17,45 +26,188 @@ metadata: name: default namespace: istio-system spec: - members: - - <1> + members: <1> + - knative-serving + - ---- <1> A list of namespaces to be integrated with {ProductShortName}. -. Create a network policy that permits traffic flow from Knative system pods to Knative services: -.. Add the `serving.knative.openshift.io/system-namespace=true` label to the `knative-serving` namespace: ++ +[IMPORTANT] +==== +This list of namespaces must include the `knative-serving` namespace. +==== +. Apply the `ServiceMeshMemberRoll` resource: + [source,terminal] ---- -$ oc label namespace knative-serving serving.knative.openshift.io/system-namespace=true +$ oc apply -f ---- -.. Add the `serving.knative.openshift.io/system-namespace=true` label to the `knative-serving-ingress` namespace: +. Create the necessary gateways so that {ProductShortName} can accept traffic: ++ +.Example `knative-local-gateway` object using HTTP +[source,yaml] +---- +apiVersion: networking.istio.io/v1alpha3 +kind: Gateway +metadata: + name: knative-ingress-gateway + namespace: knative-serving +spec: + selector: + istio: ingressgateway + servers: + - port: + number: 443 + name: https + protocol: HTTPS + hosts: + - "*" + tls: + mode: SIMPLE + credentialName: <1> +--- +apiVersion: networking.istio.io/v1alpha3 +kind: Gateway +metadata: + name: knative-local-gateway + namespace: knative-serving +spec: + selector: + istio: ingressgateway + servers: + - port: + number: 8081 + name: http + protocol: HTTP <2> + hosts: + - "*" +--- +apiVersion: v1 +kind: Service +metadata: + name: knative-local-gateway + namespace: istio-system + labels: + experimental.istio.io/disable-gateway-port-translation: "true" +spec: + type: ClusterIP + selector: + istio: ingressgateway + ports: + - name: http2 + port: 80 + targetPort: 8081 +---- +<1> Add the name of your wildcard certificate. +<2> The `knative-local-gateway` serves HTTP traffic. Using HTTP means that traffic coming from outside of {ProductShortName}, but using an internal hostname, such as `example.default.svc.cluster.local`, is not encrypted. You can set up encryption for this path by creating another wildcard certificate and an additional gateway that uses a different `protocol` spec. ++ +.Example `knative-local-gateway` object using HTTPS +[source,yaml] +---- +apiVersion: networking.istio.io/v1alpha3 +kind: Gateway +metadata: + name: knative-local-gateway + namespace: knative-serving +spec: + selector: + istio: ingressgateway + servers: + - port: + number: 443 + name: https + protocol: HTTPS + hosts: + - "*" + tls: + mode: SIMPLE + credentialName: +---- +. Apply the `Gateway` resources: + [source,terminal] ---- -$ oc label namespace knative-serving-ingress serving.knative.openshift.io/system-namespace=true +$ oc apply -f ---- -.. For each namespace that you would like to integrate with {ProductShortName}, copy the following `NetworkPolicy` resource into a YAML file: +. Install Knative Serving by creating the following `KnativeServing` custom resource definition (CRD), which also enables the Istio integration: + [source,yaml] ---- -apiVersion: networking.k8s.io/v1 -kind: NetworkPolicy +apiVersion: operator.knative.dev/v1alpha1 +kind: KnativeServing metadata: - name: allow-from-serving-system-namespace - namespace: + name: knative-serving + namespace: knative-serving spec: ingress: - - from: - - namespaceSelector: - matchLabels: - serving.knative.openshift.io/system-namespace: "true" - podSelector: {} - policyTypes: - - Ingress + istio: + enabled: true <1> + deployments: <2> + - name: activator + annotations: + "sidecar.istio.io/inject": "true" + "sidecar.istio.io/rewriteAppHTTPProbers": "true" + - name: autoscaler + annotations: + "sidecar.istio.io/inject": "true" + "sidecar.istio.io/rewriteAppHTTPProbers": "true" ---- -.. Apply the `NetworkPolicy` resource: +<1> Enables Istio integration. +<2> Enables sidecar injection for Knative Serving data plane pods. +. Apply the `KnativeServing` resource: + [source,terminal] ---- $ oc apply -f ---- +. Create a Knative Service that has sidecar injection enabled and uses a pass-through route: ++ +[source,yaml] +---- +apiVersion: serving.knative.dev/v1 +kind: Service +metadata: + name: + namespace: <1> + annotations: + serving.knative.openshift.io/enablePassthrough: "true" <2> +spec: + template: + metadata: + annotations: + sidecar.istio.io/inject: "true" <3> + sidecar.istio.io/rewriteAppHTTPProbers: "true" + spec: + containers: + - image: +---- +<1> A namespace that is part of the Service Mesh member roll. +<2> Instructs Knative Serving to generate an {product-title} pass-through enabled route, so that the certificates you have generated are served through the ingress gateway directly. +<3> Injects {ProductShortName} sidecars into the Knative service pods. +. Apply the `Service` resource: ++ +[source,terminal] +---- +$ oc apply -f +---- + +.Verification + +* Access your serverless application by using a secure connection that is now trusted by the CA: ++ +[source,terminal] +---- +$ curl --cacert root.crt +---- ++ +.Example command +[source,terminal] +---- +$ curl --cacert root.crt https://hello-default.apps.openshift.example.com +---- ++ +.Example output +[source,terminal] +---- +Hello Openshift! +---- diff --git a/modules/serverless-ossm-v1x-jwt.adoc b/modules/serverless-ossm-v1x-jwt.adoc index 7a5d06356aa8..a00f7416de73 100644 --- a/modules/serverless-ossm-v1x-jwt.adoc +++ b/modules/serverless-ossm-v1x-jwt.adoc @@ -1,18 +1,13 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm-jwt.adoc - [id="serverless-ossm-v1x-jwt_{context}"] = Using JSON Web Token authentication with {ProductShortName} 1.x and {ServerlessProductName} .Procedure . Create a policy in a serverless application namespace which is a member in the `ServiceMeshMemberRoll` object, that only allows requests with valid JSON Web Tokens (JWT): -.. Copy the following `Policy` resource into a YAML file: + [IMPORTANT] ==== -The paths `/metrics` and `/healthz` must be included in `excludedPaths` because they are accessed from system Pods in the `knative-serving` namespace. +The paths `/metrics` and `/healthz` must be included in `excludedPaths` because they are accessed from system pods in the `knative-serving` namespace. ==== + [source,yaml] @@ -35,7 +30,7 @@ spec: ---- <1> The path on your application to collect metrics by system pod. <2> The path on your application to probe by system pod. -.. Apply the `Policy` resource: +. Apply the `Policy` resource: + [source,terminal] ---- @@ -44,7 +39,7 @@ $ oc apply -f .Verification -. If you try to use a `curl` request to get the Knative service URL, it is denied. +. If you try to use a `curl` request to get the Knative service URL, it is denied: + [source,terminal] ---- @@ -57,7 +52,7 @@ $ curl http://hello-example-default.apps.mycluster.example.com/ Origin authentication failed. ---- . Verify the request with a valid JWT. -.. Get the valid JWT token by entering the following command: +.. Get the valid JWT token: + [source,terminal] ---- @@ -70,7 +65,7 @@ $ TOKEN=$(curl https://raw.githubusercontent.com/istio/istio/release-1.6/securit $ curl http://hello-example-default.apps.mycluster.example.com/ -H "Authorization: Bearer $TOKEN" ---- + -The request is now allowed. +The request is now allowed: + .Example output [source,terminal] diff --git a/modules/serverless-ossm-v1x-tls.adoc b/modules/serverless-ossm-v1x-tls.adoc index 757fcdb0bb3a..35520a32f470 100644 --- a/modules/serverless-ossm-v1x-tls.adoc +++ b/modules/serverless-ossm-v1x-tls.adoc @@ -1,7 +1,3 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm-tls.adoc - [id="serverless-ossm-v1x-tls_{context}"] = Configuring Transport Layer Security for a custom domain using {ProductName} 1.x diff --git a/modules/serverless-ossm-v2x-jwt.adoc b/modules/serverless-ossm-v2x-jwt.adoc index b59f151ed6cf..0bdc2fedf3a9 100644 --- a/modules/serverless-ossm-v2x-jwt.adoc +++ b/modules/serverless-ossm-v2x-jwt.adoc @@ -1,13 +1,9 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm-jwt.adoc - [id="serverless-ossm-v2x-jwt_{context}"] = Using JSON Web Token authentication with {ProductShortName} 2.x and {ServerlessProductName} .Procedure -. Create the `RequestAuthentication` resource in each serverless application namespace that is a member in the `ServiceMeshMemberRoll` object, by copying the following code into a YAML file: +. Create a `RequestAuthentication` resource in each serverless application namespace that is a member in the `ServiceMeshMemberRoll` object: + [source,yaml] ---- @@ -27,7 +23,7 @@ spec: ---- $ oc apply -f ---- -. Allow access to the `RequestAuthenticaton` resource from system pods for each serverless application namespace that is a member in the `ServiceMeshMemberRoll` object, by copying the following `AuthorizationPolicy` resources into a YAML file: +. Allow access to the `RequestAuthenticaton` resource from system pods for each serverless application namespace that is a member in the `ServiceMeshMemberRoll` object, by creating the following `AuthorizationPolicy` resource: + [source,yaml] ---- @@ -47,13 +43,13 @@ spec: ---- <1> The path on your application to collect metrics by system pod. <2> The path on your application to probe by system pod. -. Apply the `AuthorizationPolicy` resource YAML file: +. Apply the `AuthorizationPolicy` resource: + [source,terminal] ---- $ oc apply -f ---- -. For each serverless application namespace that is a member in the `ServiceMeshMemberRoll` object, copy the following `AuthorizationPolicy` resource, into a YAML file: +. For each serverless application namespace that is a member in the `ServiceMeshMemberRoll` object, create the following `AuthorizationPolicy` resource: + [source,yaml] ---- @@ -69,7 +65,7 @@ spec: - source: requestPrincipals: ["testing@secure.istio.io/testing@secure.istio.io"] ---- -. Apply the `AuthorizationPolicy` resource YAML file: +. Apply the `AuthorizationPolicy` resource: + [source,terminal] ---- @@ -78,8 +74,9 @@ $ oc apply -f .Verification -. If you try to use a `curl` request to get the Knative service URL, it is denied. +. If you try to use a `curl` request to get the Knative service URL, it is denied: + +.Example command [source,terminal] ---- $ curl http://hello-example-1-default.apps.mycluster.example.com/ @@ -91,7 +88,7 @@ $ curl http://hello-example-1-default.apps.mycluster.example.com/ RBAC: access denied ---- . Verify the request with a valid JWT. -.. Get the valid JWT token by entering the following command: +.. Get the valid JWT token: + [source,terminal] ---- @@ -104,7 +101,7 @@ $ TOKEN=$(curl https://raw.githubusercontent.com/istio/istio/release-1.8/securit $ curl -H "Authorization: Bearer $TOKEN" http://hello-example-1-default.apps.example.com ---- + -The request is now allowed. +The request is now allowed: + .Example output [source,terminal] diff --git a/modules/serverless-ossm-v2x-tls.adoc b/modules/serverless-ossm-v2x-tls.adoc index b6124bbe8371..651d8eafb3b1 100644 --- a/modules/serverless-ossm-v2x-tls.adoc +++ b/modules/serverless-ossm-v2x-tls.adoc @@ -1,7 +1,3 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm-tls.adoc - [id="serverless-ossm-v2x-tls_{context}"] = Configuring Transport Layer Security for a custom domain using {ProductName} 2.x diff --git a/modules/serverless-service-mesh-resources.adoc b/modules/serverless-service-mesh-resources.adoc index a9985184c7d6..db391820978a 100644 --- a/modules/serverless-service-mesh-resources.adoc +++ b/modules/serverless-service-mesh-resources.adoc @@ -1,7 +1,3 @@ -// Module included in the following assemblies: -// -// * serverless/networking/serverless-ossm-custom-domains.adoc - [id="serverless-service-mesh-resources_{context}"] = Creating necessary {ProductShortName} resources @@ -9,15 +5,14 @@ You can use the following procedure to create necessary resources for using {Pro .Procedure -. Create an Istio gateway to accept traffic. -.. Create a YAML file, and copy the following YAML into it: +. Create an Istio gateway to accept traffic: + [source,yaml] ---- apiVersion: networking.istio.io/v1alpha3 kind: Gateway metadata: - name: default-gateway + name: <1> spec: selector: istio: ingressgateway @@ -29,14 +24,14 @@ spec: hosts: - "*" ---- -.. Apply the YAML file: +<1> The namespace where your Knative services have been created. This namespace must be a member of the Service Mesh member roll. +. Apply the `Gateway` resource: + [source,terminal] ---- $ oc apply -f ---- -. Create an Istio `VirtualService` object to rewrite the host header. -.. Create a YAML file, and copy the following YAML into it: +. Create an Istio virtual service to rewrite the host header: + [source,yaml] ---- @@ -59,14 +54,14 @@ spec: number: 80 ---- <1> Your Knative service in the format `..svc`. -.. Apply the YAML file: +. Apply the `VirtualService` resource: + [source,terminal] ---- $ oc apply -f ---- -. Create an Istio `ServiceEntry` object. This is required for {ServerlessProductName} because Kourier is outside of the service mesh. -.. Create a YAML file, and copy the following YAML into it: + +. Create an Istio service entry. This is required for {ServerlessProductName} because Kourier is outside of the {ProductShortName}: + [source,yaml] ---- @@ -87,14 +82,14 @@ spec: resolution: DNS ---- <1> Your Knative service in the format `..svc`. -.. Apply the YAML file: +. Apply the `ServiceEntry` resource: + [source,terminal] ---- $ oc apply -f ---- -. Create an {product-title} route that points to the `VirtualService` object. -.. Create a YAML file, and copy the following YAML into it: + +. Create an {product-title} route that points to the `VirtualService` object: + [source,yaml] ---- @@ -112,10 +107,9 @@ spec: name: istio-ingressgateway ---- <1> The {product-title} route must be created in the same namespace as the -`ServiceMeshControlPlane` resource. In this example, the `ServiceMeshControlPlane` resource is +`ServiceMeshControlPlane`. In this example, the `ServiceMeshControlPlane` is deployed in the `istio-system` namespace. - -.. Apply the YAML file: +. Apply the `Route` resource: + [source,terminal] ---- diff --git a/modules/serverlesss-ossm-external-certs.adoc b/modules/serverlesss-ossm-external-certs.adoc new file mode 100644 index 000000000000..69757010e5ea --- /dev/null +++ b/modules/serverlesss-ossm-external-certs.adoc @@ -0,0 +1,45 @@ +[id="serverlesss-ossm-external-certs_{context}"] += Creating a certificate to encrypt incoming external traffic + +By default, the {ProductShortName} mTLS feature only secures traffic inside of the {ProductShortName} itself, between the ingress gateway and individual pods that have sidecars. To encrypt traffic as it flows into the {product-title} cluster, you must generate a certificate before you enable the {ServerlessProductName} and {ProductShortName} integration. + +.Procedure + +. Create a root certificate and private key that signs the certificates for your Knative services: ++ +[source,terminal] +---- +$ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 \ + -subj '/O=Example Inc./CN=example.com' \ + -keyout root.key \ + -out root.crt +---- +. Create a wildcard certificate: ++ +[source,terminal] +---- +$ openssl req -nodes -newkey rsa:2048 \ + -subj "/CN=*.apps.openshift.example.com/O=Example Inc." \ + -keyout wildcard.key \ + -out wildcard.csr +---- +. Sign the wildcard certificate: ++ +[source,terminal] +---- +$ openssl x509 -req -days 365 -set_serial 0 \ + -CA root.crt \ + -CAkey root.key \ + -in wildcard.csr \ + -out wildcard.crt +---- +. Create a secret by using the wildcard certificate: ++ +[source,terminal] +---- +$ oc create -n istio-system secret tls wildcard-certs \ + --key=wildcard.key \ + --cert=wildcard.crt +---- ++ +This certificate is picked up by the gateways created when you integrate {ServerlessProductName} with {ProductShortName}, so that the ingress gateway serves traffic with this certificate. diff --git a/serverless/admin_guide/serverless-ossm-setup.adoc b/serverless/admin_guide/serverless-ossm-setup.adoc new file mode 100644 index 000000000000..5854d86bd88d --- /dev/null +++ b/serverless/admin_guide/serverless-ossm-setup.adoc @@ -0,0 +1,40 @@ +include::modules/serverless-document-attributes.adoc[] +include::modules/ossm-document-attributes.adoc[] +[id="serverless-ossm-setup"] += Integrating Service Mesh with OpenShift Serverless +:context: serverless-ossm-setup +include::modules/common-attributes.adoc[] + +toc::[] + +Using {ProductShortName} with {ServerlessProductName} enables developers to configure additional networking and routing options. + +The {ServerlessOperatorName} provides Kourier as the default ingress for Knative. However, you can use {ProductShortName} with {ServerlessProductName} whether Kourier is enabled or not. Integrating with Kourier disabled allows you to configure additional networking and routing options that the Kourier ingress does not support. + +[IMPORTANT] +==== +{ServerlessProductName} only supports the use of {ProductName} functionality that is explicitly documented in this guide, and does not support other undocumented features. +==== + +// without kourier +[id="serverless-ossm-setup-native"] +== Integrating {ProductShortName} with {ServerlessProductName} natively + +Integrating {ProductShortName} with {ServerlessProductName} natively, without Kourier, allows you to use additional networking and routing options that are not supported by the default Kourier ingress, such as mTLS functionality. + +:FeatureName: mTLS for {ServerlessProductName} +include::modules/technology-preview.adoc[leveloffset=+2] + +The examples in the following procedures use the domain `example.com`. The example certificate for this domain is used as a certificate authority (CA) that signs the subdomain certificate. + +To complete and verify these procedures in your deployment, you need either a certificate signed by a widely trusted public CA or a CA provided by your organization. Example commands must be adjusted according to your domain, subdomain, and CA. + +You must configure the wildcard certificate to match the domain of your {product-title} cluster. For example, if your {product-title} console address is `https://console-openshift-console.apps.openshift.example.com`, you must configure the wildcard certificate so that the domain is `*.apps.openshift.example.com`. For more information about configuring wildcard certificates, see the following topic about _Creating a certificate to encrypt incoming external traffic_. + +If you want to use any domain name, including those which are not subdomains of the default {product-title} cluster domain, you must set up domain mapping for those domains. For more information, see the {ServerlessProductName} documentation on xref:../../serverless/knative_serving/serverless-custom-domains.adoc#serverless-create-domain-mapping_serverless-custom-domains[Creating a custom domain mapping]. + +include::modules/serverlesss-ossm-external-certs.adoc[leveloffset=+2] +include::modules/serverless-ossm-setup.adoc[leveloffset=+2] + +// With kourier +include::modules/serverless-ossm-setup-with-kourier.adoc[leveloffset=+1] diff --git a/serverless/networking/serverless-configuring-routes.adoc b/serverless/knative_serving/serverless-configuring-routes.adoc similarity index 100% rename from serverless/networking/serverless-configuring-routes.adoc rename to serverless/knative_serving/serverless-configuring-routes.adoc diff --git a/serverless/knative_serving/serverless-custom-domains.adoc b/serverless/knative_serving/serverless-custom-domains.adoc new file mode 100644 index 000000000000..b30d97dd1a76 --- /dev/null +++ b/serverless/knative_serving/serverless-custom-domains.adoc @@ -0,0 +1,51 @@ +include::modules/serverless-document-attributes.adoc[] +include::modules/ossm-document-attributes.adoc[] +[id="serverless-custom-domains"] += Configuring a custom domain for a Knative service +:context: serverless-custom-domains +include::modules/common-attributes.adoc[] + +toc::[] + +Knative services are automatically assigned a default domain name based on your cluster configuration. For example, `..example.com`. + +You can customize the domain for your Knative service by using one of the following methods: + +* Configure the service as a private service and create the required {ProductShortName} resources. ++ +[IMPORTANT] +==== +This method of configuring custom domains is only supported for clusters that have Kourier enabled. If you want to configure custom domains using only {ServerlessProductName} with {ProductShortName}, without Kourier enabled, use the `DomainMapping` resources method instead. +==== +* Map a custom domain name that you own to a Knative service by creating a `DomainMapping` resource for the service. You can also create multiple `DomainMapping` resources to map multiple domains and subdomains to a single service. ++ +[IMPORTANT] +==== +You can use `DomainMapping` resources to map custom domains either with or without Kourier enabled in your cluster, however TLS is not supported in clusters that have both Kourier and domain mapping enabled. +==== + +include::modules/serverless-create-domain-mapping.adoc[leveloffset=+1] + +[id="serverless-custom-domains-private-services"] +== Configuring custom domains for private Knative services + +You can configure a custom domain for an existing Knative service by completing the following procedures. + +.Prerequisites + +* The {ServerlessOperatorName} and Knative Serving are installed on your {product-title} cluster. +* {ProductName} version 1.x or 2.x is installed on your cluster, and the integration between {ProductName} and {ServerlessProductName} has been correctly configured. + +[IMPORTANT] +==== +{ServerlessProductName} only supports the use of {ProductName} functionality that is explicitly documented in this guide, and does not support other undocumented features. +==== + +include::modules/knative-service-cluster-local.adoc[leveloffset=+2] +include::modules/serverless-service-mesh-resources.adoc[leveloffset=+2] +include::modules/serverless-access-custom-domain.adoc[leveloffset=+2] + +[id="additional-resources_serverless-ossm-custom-domains"] +== Additional resources + +* For more information about {ProductName}, see xref:../../service_mesh/v1x/ossm-architecture.adoc#ossm-architecture-v1x[Understanding {ProductName}]. diff --git a/serverless/networking/serverless-ossm-tls.adoc b/serverless/knative_serving/serverless-ossm-tls-with-kourier.adoc similarity index 77% rename from serverless/networking/serverless-ossm-tls.adoc rename to serverless/knative_serving/serverless-ossm-tls-with-kourier.adoc index a8d477637ab3..6779bd0e5437 100644 --- a/serverless/networking/serverless-ossm-tls.adoc +++ b/serverless/knative_serving/serverless-ossm-tls-with-kourier.adoc @@ -1,7 +1,7 @@ include::modules/serverless-document-attributes.adoc[] include::modules/ossm-document-attributes.adoc[] -[id="serverless-ossm-tls"] -= Configuring Transport Layer Security for a custom domain using {ProductName} +[id="serverless-ossm-tls-with-kourier"] += Configuring Transport Layer Security for a custom domain using {ProductName} and Kourier :context: serverless-ossm-tls include::modules/common-attributes.adoc[] @@ -9,14 +9,9 @@ toc::[] You can create a Transport Layer Security (TLS) key and certificates for a custom domain and subdomain using {ProductName}. -[NOTE] -==== -{ServerlessProductName} is compatible only with full implementations of either {ProductName} 1.x or 2.x. {ServerlessProductName} does not support custom usage of some 1.x resources and some 2.x resources in the same deployment. For example, upgrading to 2.x while still using the control plane `maistra.io/v1` spec is not supported. -==== - [IMPORTANT] ==== -{ServerlessProductName} only supports the use of {ProductName} functionality that is explicitly documented in this guide, and does not support other undocumented features, such as mTLS or custom Istio ingress gateways. +{ServerlessProductName} only supports the use of {ProductName} functionality that is explicitly documented in this guide, and does not support other undocumented features. ==== [id="prerequisites_serverless-ossm-tls"] @@ -24,8 +19,13 @@ You can create a Transport Layer Security (TLS) key and certificates for a custo * Install xref:../../serverless/admin_guide/install-serverless-operator.adoc#install-serverless-operator[{ServerlessProductName}]. * Install {ProductName} xref:../../service_mesh/v1x/installing-ossm.adoc#installing-ossm-v1x[1.x] or xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm-v2x[2.x]. -* Complete the configuration steps in xref:../../serverless/networking/serverless-ossm.adoc#serverless-ossm[Using Service Mesh with OpenShift Serverless]. -* Configure a custom domain. See xref:../../serverless/networking/serverless-ossm-custom-domains.adoc#serverless-ossm-custom-domains[Using custom domains for Knative services with Service Mesh]. ++ +[IMPORTANT] +==== +{ServerlessProductName} is compatible only with full implementations of either {ProductName} 1.x or 2.x. {ServerlessProductName} does not support custom usage of some 1.x resources and some 2.x resources in the same deployment. For example, upgrading to 2.x while still using the control plane `maistra.io/v1` spec is not supported. +==== +* Complete the configuration steps in xref:../../serverless/admin_guide/serverless-ossm-setup.adoc#serverless-ossm-setup-with-kourier_serverless-ossm-setup[Integrating {ProductShortName} and {ServerlessProductName} with Kourier enabled]. +* Configure a custom domain. See xref:../../serverless/knative_serving/serverless-custom-domains.adoc#serverless-custom-domains[Configuring a custom domain for a Knative service]. * In this example, `openssl` is used to generate certificates, but you can use any certificate generation tool to create these. [IMPORTANT] diff --git a/serverless/knative_serving/serverless-ossm-with-kourier-jwt.adoc b/serverless/knative_serving/serverless-ossm-with-kourier-jwt.adoc new file mode 100644 index 000000000000..87518c56e796 --- /dev/null +++ b/serverless/knative_serving/serverless-ossm-with-kourier-jwt.adoc @@ -0,0 +1,19 @@ +include::modules/serverless-document-attributes.adoc[] +include::modules/ossm-document-attributes.adoc[] +[id="serverless-ossm-with-kourier-jwt"] += Configuring JSON Web Token authentication for Knative services +:context: serverless-ossm-with-kourier-jwt +include::modules/common-attributes.adoc[] + +toc::[] + +After the {ProductShortName} integration with {ServerlessProductName} and Kourier has been configured on your cluster, you can enable JSON Web Token (JWT) authentication for your Knative services. + +[IMPORTANT] +==== +You must set the annotation `sidecar.istio.io/rewriteAppHTTPProbers: "true"` in your Knative service as {ServerlessProductName} versions 1.14.0 and higher use a HTTP probe as the readiness probe for Knative services by default. +==== + +include::modules/serverless-ossm-enable-sidecar-injection-with-kourier.adoc[leveloffset=+1] +include::modules/serverless-ossm-v2x-jwt.adoc[leveloffset=+1] +include::modules/serverless-ossm-v1x-jwt.adoc[leveloffset=+1] diff --git a/serverless/networking/images b/serverless/networking/images deleted file mode 120000 index 5e67573196d8..000000000000 --- a/serverless/networking/images +++ /dev/null @@ -1 +0,0 @@ -../images \ No newline at end of file diff --git a/serverless/networking/modules b/serverless/networking/modules deleted file mode 120000 index 464b823aca16..000000000000 --- a/serverless/networking/modules +++ /dev/null @@ -1 +0,0 @@ -../modules \ No newline at end of file diff --git a/serverless/networking/serverless-domain-mapping.adoc b/serverless/networking/serverless-domain-mapping.adoc deleted file mode 100644 index 0e519d03acb4..000000000000 --- a/serverless/networking/serverless-domain-mapping.adoc +++ /dev/null @@ -1,16 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -[id="serverless-domain-mapping"] -= Mapping a custom domain name to a Knative service -:context: serverless-domain-mapping -include::modules/common-attributes.adoc[] - -toc::[] - -Knative services are automatically assigned a default domain name based on your cluster configuration. For example, `..example.com`. - -You can map a custom domain name that you own to a Knative service by creating a `DomainMapping` custom resource (CR) for the service. You can also create multiple CRs to map multiple domains and subdomains to a single service. - -include::modules/serverless-create-domain-mapping.adoc[leveloffset=+1] -// Uncomment at 1.16.0 release -// include::modules/serverless-create-domain-mapping-kn.adoc[leveloffset=+1] -// include::modules/serverless-manage-domain-mapping-kn.adoc[leveloffset=+1] diff --git a/serverless/networking/serverless-ossm-custom-domains.adoc b/serverless/networking/serverless-ossm-custom-domains.adoc deleted file mode 100644 index 61fe9a6afbdc..000000000000 --- a/serverless/networking/serverless-ossm-custom-domains.adoc +++ /dev/null @@ -1,39 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -include::modules/ossm-document-attributes.adoc[] -[id="serverless-ossm-custom-domains"] -= Using custom domains for Knative services with {ProductShortName} -:context: serverless-ossm-custom-domains -include::modules/common-attributes.adoc[] - -toc::[] - -By default, Knative services have a fixed domain format: - -[source,terminal] ----- - -. ----- - -You can customize the domain for your Knative service by configuring the service as a private service and creating the required {ProductShortName} resources. - -[IMPORTANT] -==== -{ServerlessProductName} only supports the use of {ProductName} functionality that is explicitly documented in this guide, and does not support other undocumented features, such as mTLS or custom Istio ingress gateways. -==== - -[id="prerequisites_serverless-ossm-custom-domains"] -== Prerequisites - -* Install the xref:../../serverless/admin_guide/install-serverless-operator.adoc#install-serverless-operator[{ServerlessOperatorName}] and xref:../../serverless/admin_guide/installing-knative-serving.adoc#installing-knative-serving[Knative Serving]. -* Install xref:../../service_mesh/v1x/preparing-ossm-installation.adoc#preparing-ossm-installation-v1x[{ProductName}]. -* Complete the configuration steps in xref:../../serverless/networking/serverless-ossm.adoc#serverless-ossm[Using {ProductShortName} with {ServerlessProductName}]. -* You can configure a custom domain for an existing Knative service, or create a new sample service. To create a new service, see xref:../../serverless/knative_serving/serverless-applications.adoc#serverless-applications[Creating and managing serverless applications]. - -include::modules/knative-service-cluster-local.adoc[leveloffset=+1] -include::modules/serverless-service-mesh-resources.adoc[leveloffset=+1] -include::modules/serverless-access-custom-domain.adoc[leveloffset=+1] - -[id="additional-resources_serverless-ossm-custom-domains"] -== Additional resources - -* For more information about {ProductName}, see xref:../../service_mesh/v1x/ossm-architecture.adoc#ossm-architecture-v1x[Understanding {ProductName}]. diff --git a/serverless/networking/serverless-ossm-jwt.adoc b/serverless/networking/serverless-ossm-jwt.adoc deleted file mode 100644 index d4bcd1b6689b..000000000000 --- a/serverless/networking/serverless-ossm-jwt.adoc +++ /dev/null @@ -1,35 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -include::modules/ossm-document-attributes.adoc[] -[id="serverless-ossm-jwt"] -= Using JSON Web Token authentication with {ProductShortName} and {ServerlessProductName} -:context: serverless-ossm-jwt -include::modules/common-attributes.adoc[] - -toc::[] - -You can enable JSON Web Token (JWT) authentication for Knative services. - -[IMPORTANT] -==== -{ServerlessProductName} only supports the use of {ProductName} functionality that is explicitly documented in this guide, and does not support other undocumented features, such as mTLS or custom Istio ingress gateways. -==== - -[id="prerequisites_serverless-ossm-jwt"] -== Prerequisites - -* Install xref:../../serverless/admin_guide/install-serverless-operator.adoc#install-serverless-operator[{ServerlessProductName}]. -* Install {ProductName}. {ServerlessProductName} is supported for use with both {ProductName} version xref:../../service_mesh/v1x/installing-ossm.adoc#installing-ossm[1.x] and version xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[2.x]. -* Configure xref:../../serverless/networking/serverless-ossm.adoc#serverless-ossm[{ProductShortName} with {ServerlessProductName}], including enabling sidecar injection for your Knative services. - -[IMPORTANT] -==== -Adding sidecar injection to pods in system namespaces such as `knative-serving` and `knative-serving-ingress` is not supported. -==== - -[IMPORTANT] -==== -You must set the annotation `sidecar.istio.io/rewriteAppHTTPProbers: "true"` in your Knative service as {ServerlessProductName} versions 1.14.0 and later use an HTTP probe as the readiness probe for Knative services by default. -==== - -include::modules/serverless-ossm-v2x-jwt.adoc[leveloffset=+1] -include::modules/serverless-ossm-v1x-jwt.adoc[leveloffset=+1] diff --git a/serverless/networking/serverless-ossm.adoc b/serverless/networking/serverless-ossm.adoc deleted file mode 100644 index c16f429d4fb5..000000000000 --- a/serverless/networking/serverless-ossm.adoc +++ /dev/null @@ -1,25 +0,0 @@ -include::modules/serverless-document-attributes.adoc[] -include::modules/ossm-document-attributes.adoc[] -[id="serverless-ossm"] -= Using {ProductShortName} with {ServerlessProductName} -:context: serverless-ossm -include::modules/common-attributes.adoc[] - -toc::[] - -[IMPORTANT] -==== -{ServerlessProductName} only supports the use of {ProductName} functionality that is explicitly documented in this guide, and does not support other undocumented features, such as mTLS or custom Istio ingress gateways. -==== - -Using {ProductShortName} with {ServerlessProductName} enables developers to configure additional networking and routing options that are not supported when using {ServerlessProductName} with the default Kourier implementation. -These options include setting custom domains, using TLS certificates, and using JSON Web Token authentication. - -[id="prerequisites_serverless-ossm"] -== Prerequisites - -* Install the xref:../../serverless/admin_guide/install-serverless-operator.adoc#install-serverless-operator[{ServerlessOperatorName}] and xref:../../serverless/admin_guide/installing-knative-serving.adoc#installing-knative-serving[Knative Serving]. -* Install {ProductName}. {ServerlessProductName} is supported for use with both {ProductName} version xref:../../service_mesh/v1x/installing-ossm.adoc#installing-ossm[1.x] and version xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[2.x]. - -include::modules/serverless-ossm-setup.adoc[leveloffset=+1] -include::modules/serverless-service-mesh-enable-sidecar-injection.adoc[leveloffset=+1]