diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index d59c7028b251..afd93009c1e8 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -511,6 +511,8 @@ Topics: File: serverless-ossm-setup - Name: Using Service Mesh 2.x to isolate network traffic with OpenShift Serverless File: serverless-ossm-traffic-isolation + - Name: Integrating Service Mesh 3.x with OpenShift Serverless + File: serverless-integrating-ossm-3-x-setup - Name: Integrating OpenShift Serverless with the cost management service File: serverless-cost-management-integration - Name: Integrating OpenShift Serverless with OpenShift Pipelines diff --git a/integrations/serverless-integrating-service-mesh/serverless-integrating-ossm-3-x-setup.adoc b/integrations/serverless-integrating-service-mesh/serverless-integrating-ossm-3-x-setup.adoc new file mode 100644 index 000000000000..5099a5bf04cf --- /dev/null +++ b/integrations/serverless-integrating-service-mesh/serverless-integrating-ossm-3-x-setup.adoc @@ -0,0 +1,52 @@ +:_mod-docs-content-type: ASSEMBLY +[id="serverless-integrating-ossm-3-x-setup"] += Integrating Service Mesh 3.x with OpenShift Serverless +include::_attributes/common-attributes.adoc[] +:context: serverless-integrating-ossm-3-x-setup + +toc::[] + +[role="_abstract"] +The {ServerlessOperatorName} provides Kourier as the default ingress for Knative. However, you can use {SMProductShortName} 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, such as mTLS functionality. + +Note the following assumptions and limitations: + +* All Knative internal components, as well as Knative Services, are part of the {SMProductShortName} and have sidecars injection enabled. This means that strict mTLS is enforced within the whole mesh. All requests to Knative Services require an mTLS connection, with the client having to send its certificate, except calls coming from OpenShift Routing. + +* {ServerlessProductName} with {SMProductShortName} integration can only target *one* service mesh. Multiple meshes can be present in the cluster, but {ServerlessProductName} is only available on one of them. + +[id="prerequisites_serverless-integrating-ossm-3-x-setup"] +== Prerequisites + +* You have access to an {product-title} account with cluster administrator access. + +* You have installed the OpenShift CLI (`oc`). + +* You have installed the {ServerlessProductShortName} Operator. + +* You have installed the {SMProductName} 3.x Operator. + +* 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 {ocp-product-title} cluster. For example, if your {ocp-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 {ocp-product-title} cluster domain, you must set up domain mapping for those domains. For more information, see the {ServerlessProductName} documentation about xref:../../knative-serving/config-custom-domains/create-domain-mapping.adoc#serverless-create-domain-mapping_create-domain-mapping[Creating a custom domain mapping]. + +include::modules/serverless-ossm-external-certs.adoc[leveloffset=+1] + +[id="configuring-verifying-ossm-3-x-integration-with-serverless"] +== Configuring and verifying {SMProductShortName} 3.x integration with {ServerlessProductName} + +You can integrate {SMProductShortName} 3.x with {ServerlessProductName} to enable advanced traffic management, security, and observability for your serverless applications. This section provides the steps to verify prerequisites, install and configure both components, and confirm that the integration is functioning as expected. + +include::modules/serverless-ossm-verifying-installation-prerequisites.adoc[leveloffset=+2] + +include::modules/serverless-ossm-installing-and-configuring-openshift-service-mesh-3-x.adoc[leveloffset=+2] + +include::modules/serverless-ossm-installing-and-configuring-openshift-serverless.adoc[leveloffset=+2] + +include::modules/serverless-ossm-verifying-the-ossm-3-x-integration.adoc[leveloffset=+2] + +include::modules/serverless-ossm-disabling-network-policies.adoc[leveloffset=+1] diff --git a/modules/serverless-ossm-disabling-network-policies.adoc b/modules/serverless-ossm-disabling-network-policies.adoc index aa984110a434..27037c93434c 100644 --- a/modules/serverless-ossm-disabling-network-policies.adoc +++ b/modules/serverless-ossm-disabling-network-policies.adoc @@ -2,10 +2,11 @@ // // * /serverless/integrations/serverless-ossm-setup.adoc -:_content-type: PROCEDURE +:_mod-docs-content-type: PROCEDURE [id="serverless-ossm-disabling-network-policies_{context}"] = Disabling the default network policies +[role="_abstract"] The {ServerlessOperatorName} generates the network policies by default. To disable the default network policy generation, you can add the `serverless.openshift.io/disable-istio-net-policies-generation` annotation in the `KnativeEventing` and `KnativeServing` custom resources (CRs). .Prerequisites diff --git a/modules/serverless-ossm-installing-and-configuring-openshift-serverless.adoc b/modules/serverless-ossm-installing-and-configuring-openshift-serverless.adoc index c3895c00c203..f788b69f70ce 100644 --- a/modules/serverless-ossm-installing-and-configuring-openshift-serverless.adoc +++ b/modules/serverless-ossm-installing-and-configuring-openshift-serverless.adoc @@ -1,7 +1,8 @@ -:_content-type: PROCEDURE +:_mod-docs-content-type: PROCEDURE [id="serverless-ossm-installing-and-configuring-openshift-serverless_{context}"] = Installing and configuring {ServerlessProductShortName} +[role="_abstract"] After installing {SMProductShortName}, you need to install {ServerlessProductShortName} with a specific configuration. .Procedure @@ -16,6 +17,8 @@ kind: KnativeServing metadata: name: knative-serving namespace: knative-serving + annotations: + serverless.openshift.io/disable-istio-net-policies-generation: "true" spec: ingress: istio: @@ -57,31 +60,42 @@ kind: KnativeEventing metadata: name: knative-eventing namespace: knative-eventing + annotations: + serverless.openshift.io/disable-istio-net-policies-generation: "true" spec: config: features: - istio: enabled <1> - workloads: <2> - - name: pingsource-mt-adapter - labels: - "sidecar.istio.io/inject": "true" - annotations: - "sidecar.istio.io/rewriteAppHTTPProbers": "true" - - name: imc-dispatcher - labels: - "sidecar.istio.io/inject": "true" - annotations: - "sidecar.istio.io/rewriteAppHTTPProbers": "true" - - name: mt-broker-ingress - labels: - "sidecar.istio.io/inject": "true" - annotations: - "sidecar.istio.io/rewriteAppHTTPProbers": "true" - - name: mt-broker-filter - labels: - "sidecar.istio.io/inject": "true" - annotations: - "sidecar.istio.io/rewriteAppHTTPProbers": "true" + istio: enabled # <1> + workloads: # <2> + - name: pingsource-mt-adapter + labels: + sidecar.istio.io/inject: "true" + annotations: + sidecar.istio.io/rewriteAppHTTPProbers: "true" + + - name: imc-dispatcher + labels: + sidecar.istio.io/inject: "true" + annotations: + sidecar.istio.io/rewriteAppHTTPProbers: "true" + + - name: mt-broker-ingress + labels: + sidecar.istio.io/inject: "true" + annotations: + sidecar.istio.io/rewriteAppHTTPProbers: "true" + + - name: mt-broker-filter + labels: + sidecar.istio.io/inject: "true" + annotations: + sidecar.istio.io/rewriteAppHTTPProbers: "true" + + - name: job-sink + labels: + sidecar.istio.io/inject: "true" + annotations: + sidecar.istio.io/rewriteAppHTTPProbers: "true" ---- <1> Enable Eventing Istio controller to create a `DestinationRule` for each `InMemoryChannel` or `KafkaChannel` service. <2> Enable sidecar injection for Knative Eventing pods. diff --git a/modules/serverless-ossm-installing-and-configuring-openshift-service-mesh-3-x.adoc b/modules/serverless-ossm-installing-and-configuring-openshift-service-mesh-3-x.adoc new file mode 100644 index 000000000000..2630df846a0f --- /dev/null +++ b/modules/serverless-ossm-installing-and-configuring-openshift-service-mesh-3-x.adoc @@ -0,0 +1,236 @@ +:_mod-docs-content-type: PROCEDURE +[id="serverless-ossm-installing-and-configuring-openshift-service-mesh-3-x_{context}"] += Installing and configuring {SMProductShortName} 3.x + +[role="_abstract"] +You can integrate {SMProductShortName} 3.x with {ServerlessProductShortName} by installing and configuring the required Istio components, gateways, and Knative Serving resources. Once these resources are configured, you can deploy the Knative Serving instance with Istio enabled to ensure that your serverless workloads run within the {SMProductShortName} environment. + +.Procedure + +. Create an `Istio` resource in the `istio-system` namespace with the following configuration: ++ +[source,yaml] +---- +apiVersion: sailoperator.io/v1 +kind: Istio +metadata: + name: default +spec: + values: + meshConfig: + defaultConfig: + terminationDrainDuration: 35s + updateStrategy: + inactiveRevisionDeletionGracePeriodSeconds: 30 + type: InPlace + namespace: istio-system + version: v1.26-latest +---- + +. Apply the resource by running the following commands: ++ +[source,terminal] +---- +$ oc new-project istio-system +---- ++ +[source,terminal] +---- +$ oc apply -f istio.yaml +---- + +. Create an `IstioCNI` resource in the `istio-cni` namespace with the following configuration: ++ +[source,yaml] +---- +apiVersion: sailoperator.io/v1 +kind: IstioCNI +metadata: + name: default +spec: + namespace: istio-cni + version: v1.26-latest +---- + +. Apply the resource by running the following commands: ++ +[source,terminal] +---- +$ oc new-project istio-cni +---- ++ +[source,terminal] +---- +$ oc apply -f istio-cni.yaml +---- + +. Create a file named `gateway-deploy.yaml` with the following configuration: ++ +[source,yaml] +---- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: knative-istio-ingressgateway + namespace: knative-serving-ingress +spec: + selector: + matchLabels: + knative: ingressgateway + template: + metadata: + annotations: + inject.istio.io/templates: gateway <1> + labels: + knative: ingressgateway <2> + sidecar.istio.io/inject: "true" <3> + spec: + containers: + - name: istio-proxy + image: auto <4> + +--- +# Set up roles to allow reading credentials for TLS +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: istio-ingressgateway-sds + namespace: knative-serving-ingress +rules: + - apiGroups: [""] + resources: ["secrets"] + verbs: ["get", "watch", "list"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: istio-ingressgateway-sds + namespace: knative-serving-ingress +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: istio-ingressgateway-sds +subjects: + - kind: ServiceAccount + name: default +---- ++ +<1> Select the gateway injection template rather than the default sidecar template. +<2> Set a unique label for the gateway. This is required to ensure Gateways can select this workload. +<3> Enable gateway injection. +<4> The image will automatically update each time the pod starts. + +. Apply the resource by running the following commands: ++ +[source,terminal] +---- +$ oc apply -f gateway-deploy.yaml +---- + +. Create gateway resources for the Knative Serving component by creating a file named `serving-gateways.yaml` with the following configuration: ++ +[source,yaml] +---- +########################################################### +# cluster external +########################################################### +apiVersion: v1 +kind: Service +metadata: + name: knative-istio-ingressgateway + namespace: knative-serving-ingress +spec: + type: ClusterIP + selector: + knative: ingressgateway + ports: + - name: http2 + port: 80 + targetPort: 8080 + - name: https + port: 443 + targetPort: 8443 +--- +apiVersion: networking.istio.io/v1beta1 +kind: Gateway +metadata: + name: knative-ingress-gateway + namespace: knative-serving +spec: + selector: + knative: ingressgateway + servers: + - hosts: + - '*' + port: + name: https + number: 443 + protocol: HTTPS + tls: + credentialName: wildcard-certs + mode: SIMPLE +--- +########################################################### +# cluster local +########################################################### +apiVersion: v1 +kind: Service +metadata: + labels: + experimental.istio.io/disable-gateway-port-translation: "true" + name: knative-local-gateway + namespace: knative-serving-ingress +spec: + ports: + - name: http2 + port: 80 + protocol: TCP + targetPort: 8081 + selector: + knative: ingressgateway + type: ClusterIP +--- +apiVersion: networking.istio.io/v1beta1 +kind: Gateway +metadata: + name: knative-local-gateway + namespace: knative-serving +spec: + selector: + knative: ingressgateway + servers: + - hosts: + - '*' + port: + name: http + number: 8081 + protocol: HTTP +---- + +. Apply the resource by running the following commands: ++ +[source,terminal] +---- +$ oc apply -f serving-gateways.yaml +---- + +. Create a `PeerAuthentication` resource in the `istio-system` namespace to enforce mTLS across the mesh with the following configuration: ++ +[source,yaml] +---- +apiVersion: security.istio.io/v1 +kind: PeerAuthentication +metadata: + name: mesh-mtls + namespace: istio-system +spec: + mtls: + mode: STRICT +---- + +. Apply the resource by running the following commands: ++ +[source,terminal] +---- +$ oc apply -f peerauth.yaml +---- diff --git a/modules/serverless-ossm-verifying-installation-prerequisites.adoc b/modules/serverless-ossm-verifying-installation-prerequisites.adoc index 600fe896268a..9b03b0c5b4b1 100644 --- a/modules/serverless-ossm-verifying-installation-prerequisites.adoc +++ b/modules/serverless-ossm-verifying-installation-prerequisites.adoc @@ -1,7 +1,8 @@ -:_content-type: PROCEDURE +:_mod-docs-content-type: PROCEDURE [id="serverless-ossm-verifying-installation-prerequisites_{context}"] = Verifying installation prerequisites +[role="_abstract"] Before installing and configuring the {SMProductShortName} integration with {ServerlessProductShortName}, verify that the prerequisites have been met. .Procedure diff --git a/modules/serverless-ossm-verifying-the-integration.adoc b/modules/serverless-ossm-verifying-the-integration.adoc index 03f5ea1bf21b..1dfda0822c89 100644 --- a/modules/serverless-ossm-verifying-the-integration.adoc +++ b/modules/serverless-ossm-verifying-the-integration.adoc @@ -1,7 +1,8 @@ -:_content-type: PROCEDURE +:_mod-docs-content-type: PROCEDURE [id="serverless-ossm-verifying-the-integration_{context}"] = Verifying the integration +[role="_abstract"] After installing {SMProductShortName} and {ServerlessProductShortName} with Istio enabled, you can verify that the integration works. .Procedure diff --git a/modules/serverless-ossm-verifying-the-ossm-3-x-integration.adoc b/modules/serverless-ossm-verifying-the-ossm-3-x-integration.adoc new file mode 100644 index 000000000000..db15d1df0750 --- /dev/null +++ b/modules/serverless-ossm-verifying-the-ossm-3-x-integration.adoc @@ -0,0 +1,119 @@ +:_mod-docs-content-type: PROCEDURE +[id="serverless-ossm-verifying-the-ossm-3-x-integration_{context}"] += Verifying the integration setup for {SMProductShortName} 3.x + +[role="_abstract"] +After installing and configuring {SMProductShortName} 3.x with {ServerlessProductShortName}, you can verify that the integration is working correctly. This verification ensures that the Service Mesh components, gateways, and Knative Serving configuration are properly set up and that serverless workloads can communicate securely within the mesh. + +The folloiwng test deploys a simple Knative Service and verifies sidecar injection, mTLS compatibility, and passthrough via the ingress gateway. + +.Procedure + +. Verify Istio, Istio CNI, and Knative components are running, by entering the following commands: ++ +[source,terminal] +---- +$ oc get pods -n istio-system +---- ++ +[source,terminal] +---- +$ oc get pods -n istio-cni +---- ++ +[source,terminal] +---- +$ oc get pods -n knative-serving +---- + +. Verify gateway services exist by entering the following command: ++ +[source,terminal] +---- +$ oc get svc -n knative-serving-ingress +---- + +. Create a test namespace by entering the following command: ++ +[source,terminal] +---- +$ oc new-project demo +---- + +. Create the sample Knative Service manifest and Save as `hello-service.yaml` with the following configuration: ++ +[source,yaml] +---- +apiVersion: serving.knative.dev/v1 +kind: Service +metadata: + annotations: + serving.knative.openshift.io/enablePassthrough: "true" # <1> + name: hello-service + namespace: demo +spec: + template: + metadata: + labels: + sidecar.istio.io/inject: "true" # <2> + annotations: + sidecar.istio.io/rewriteAppHTTPProbers: "true" # <3> + spec: + containers: + - image: quay.io/openshift-knative/showcase +---- ++ +<1> `serving.knative.openshift.io/enablePassthrough: "true"` configures the ingress to allow TLS passthrough via the Istio gateway. +<2> `sidecar.istio.io/inject: "true"` ensures the Istio proxy is injected. +<3> `sidecar.istio.io/rewriteAppHTTPProbers: "true"` makes Knative health probes work with mTLS. + +. Apply the Knative Service by entering the following command: ++ +[source,terminal] +---- +$ oc apply -f hello-service.yaml +---- + +. Confirm sidecar injection and pod readiness by entering the following commands: ++ +[source,terminal] +---- +$ oc get pods -n demo +---- ++ +[source,terminal] +---- +$ oc get pod -n demo -l serving.knative.dev/service=hello-service -o jsonpath='{.items[0].spec.containers[*].name}{"\n"}' +---- + +. Fetch the service URL by entering the following commands: ++ +[source,terminal] +---- +$ oc get ksvc hello-service -n demo -o jsonpath='{.status.url}{"\n"}' +---- + +. Call the service by entering any one of the following commands: + +* Option A: If you have a trusted certificate set on the ingress domain, enter the folloing command: ++ +[source,terminal] +---- +$ curl https://$(oc get ksvc hello-service -n demo -o jsonpath='{.status.url}' | sed 's#https://##') +---- + +* Option B: If you are using a custom or self-signed certificate, use -k or provide your CA file with --cacert by entering the following command ++ +[source,terminal] +---- +$ curl --cacert https://$(oc get ksvc hello-service -n demo -o jsonpath='{.status.url}' | sed 's#https://##') +---- ++ +You should see an output similar to the following example: ++ +[source,terminal] +---- +{"artifact":"knative-showcase","greeting":"Welcome"} +---- ++ +The exact JSON values might vary, but the response should indicate that the `knative-showcase` application is running successfully.