Merge pull request #52191 from rh-tokeefe/OSSMDOC-702

OSSMDOC-702: Document gateway injection

Author: rolfedh

modules/ossm-automatic-gateway-injection.adoc

@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v2x/ossm-traffic-manage.adoc
+
+:_content-type: CONCEPT
+[id="ossm-automatic-gateway-injection_{context}"]
+= Enabling gateway injection
+
+Gateway configurations apply to standalone Envoy proxies running at the edge of the mesh, rather than sidecar Envoy proxies running alongside your service workloads. Because gateways are Envoy proxies, you can configure {SMProductShortName} to inject gateways automatically, similar to how you can inject sidecars.
+
+Using automatic injection for gateways, you can deploy and manage gateways independent from the `ServiceMeshControlPlane` resource and manage the gateways with your user applications. Using auto-injection for gateway deployments gives developers full control over the gateway deployment while simplifying operations. When a new upgrade is available, or a configuration has changed, you restart the gateway pods to update them. Doing so makes the experience of operating a gateway deployment the same as operating sidecars.
+
+[NOTE]
+====
+Injection is disabled by default for the `ServiceMeshControlPlane` namespace, for example the `istio-system` namespace. As a security best practice, deploy gateways in a different namespace from the control plane.
+====

modules/ossm-deploying-automatic-gateway-injection.adoc

@@ -0,0 +1,81 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v2x/ossm-traffic-manage.adoc
+
+:_content-type: PROCEDURE
+[id="ossm-deploying-automatic-gateway-injection_{context}"]
+= Deploying automatic gateway injection
+
+When deploying a gateway, you must opt-in to injection by adding an injection label or annotation to the gateway `deployment` object. The following example  `ConfigMap` object deploys a gateway with automatic injection.
+
+.Prerequisites
+
+* The namespace must be a member of the mesh by defining it in the `ServiceMeshMemberRoll` or by creating a `ServiceMeshMember` resource.
+
+.Example deployment with annotations
+[source,yaml]
+----
+  apiVersion: v1
+  kind: Service
+  metadata:
+    name: istio-ingressgateway
+    namespace: istio-ingress
+  spec:
+    type: LoadBalancer
+    selector:
+      istio: ingressgateway
+    ports:
+    - port: 80
+      name: http
+    - port: 443
+      name: https
+  ---
+  apiVersion: apps/v1
+  kind: Deployment
+  metadata:
+    name: istio-ingressgateway
+    namespace: istio-ingress
+  spec:
+    selector:
+      matchLabels:
+        istio: ingressgateway
+    template:
+      metadata:
+        annotations:
+          inject.istio.io/templates: gateway <1>
+        labels:
+          istio: ingressgateway <2>
+          sidecar.istio.io/inject: "true" <3>
+      spec:
+        containers:
+        - name: istio-proxy
+          image: auto <4>
+  ---
+  apiVersion: rbac.authorization.k8s.io/v1 <5>
+  kind: Role
+  metadata:
+    name: istio-ingressgateway-sds
+    namespace: istio-ingress
+  rules:
+    - apiGroups: [""]
+      resources: ["secrets"]
+      verbs: ["get", "watch", "list"]
+  ---
+  apiVersion: rbac.authorization.k8s.io/v1
+  kind: RoleBinding
+  metadata:
+   name: istio-ingressgateway-sds
+   namespace: istio-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 setting is required to ensure Gateways can select this workload.
+<3> Enable gateway injection. If connecting to a revisioned control plane, replace with `istio.io/rev: revision-name`.
+<4> The image automatically updates each time the pod starts.
+<5> Set up roles to allow reading credentials for TLS.

service_mesh/v2x/ossm-traffic-manage.adoc

@@ -6,16 +6,18 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-{SMProductName} lets you control the flow of traffic and API calls between services. Some services in your service mesh may need to communicate within the mesh and others may need to be hidden. You can manage the traffic to hide specific backend services, expose services, create testing or versioning deployments, or add a security layer on a set of services.
+Using {SMProductName}, you can control the flow of traffic and API calls between services. Some services in your service mesh might need to communicate within the mesh and others might need to be hidden. You can manage the traffic to hide specific backend services, expose services, create testing or versioning deployments, or add a security layer on a set of services.
 
-//NEW module
 include::modules/ossm-gateways.adoc[leveloffset=+1]
-//Gateway injection topic will go HERE
+
+include::modules/ossm-automatic-gateway-injection.adoc[leveloffset=+2]
+
+include::modules/ossm-deploying-automatic-gateway-injection.adoc[leveloffset=+2]
+
 include::modules/ossm-routing-ingress.adoc[leveloffset=+2]
 
 include::modules/ossm-routing-gateways.adoc[leveloffset=+2]
 
-
 [id="ossm-auto-route_{context}"]
 == Understanding automatic routes