From ac682a9c053f7bba678a1eac15eda6a66a673a4a Mon Sep 17 00:00:00 2001 From: kurokobo Date: Thu, 22 Feb 2024 04:36:50 +0900 Subject: [PATCH] docs: improve documentation for awxmeshingress (#1724) * add descriptions and examples for awxmeshingress * convert list to table * add note for image * correct minor wording issues * apply suggested changes from code review for docs/user-guide/advanced-configuration/mesh-ingress.md Co-authored-by: Seth Foster --- .../advanced-configuration/mesh-ingress.md | 244 ++++++++++++------ 1 file changed, 160 insertions(+), 84 deletions(-) diff --git a/docs/user-guide/advanced-configuration/mesh-ingress.md b/docs/user-guide/advanced-configuration/mesh-ingress.md index 43919b8d..cbaa9dd0 100644 --- a/docs/user-guide/advanced-configuration/mesh-ingress.md +++ b/docs/user-guide/advanced-configuration/mesh-ingress.md @@ -11,9 +11,14 @@ For more information about remote execution and hop nodes and how to create them ## Deploy and configure AWXMeshIngress -### On Red Hat OpenShift with operator managed Route +!!! note + The mesh ingress uses the `control_plane_ee_image` and `image_pull_policy` fields of the AWX instance to determine image and policy to be adopted. + Defaulted to `quay.io/ansible/awx-ee:latest` and `Always`. + Currently there are no dedicated parameters to specify the image and policy. -To deploy an mesh ingress on OpenShift create the AWXMeshIngress resource. +### On Red Hat OpenShift with Operator managed Route + +To deploy a mesh ingress on OpenShift, create the AWXMeshIngress resource on the namespace where your AWX instance is running on. Example: @@ -27,21 +32,136 @@ spec: deployment_name: ``` -### User managed Ingress +### On Kubernetes with Operator managed Ingress (NGINX) -UNDER CONSTRUCTION (contribution welcome) +To deploy a mesh ingress on Kubernetes cluster which has [NGINX Ingress Controller](https://www.nginx.com/products/nginx-ingress-controller/), create the AWXMeshIngress resource on the namespace where your AWX instance is running on. -### Operator managed Ingress +Note that AWXMeshIngress requires [SSL Passthrough](https://kubernetes.github.io/ingress-nginx/user-guide/tls/#ssl-passthrough) enabled which is disabled by default. Ensure it is enabled on your NGINX Ingress Controller. -UNDER CONSTRUCTION (contribution welcome) +By specifying `ingress_controller` as `nginx`, AWX Operator will generate Ingress resource that has `nginx.ingress.kubernetes.io/ssl-passthrough` annotation set to `"true"`. -### Deploy and configure AWXMeshIngress via IngressRouteTCP +Example: -UNDER CONSTRUCTION (contribution welcome) +```yaml +--- +apiVersion: awx.ansible.com/v1alpha1 +kind: AWXMeshIngress +metadata: + name: +spec: + deployment_name: + + ingress_type: Ingress + ingress_controller: nginx + ingress_class_name: nginx + + external_hostname: +``` + +### On Kubernetes with Operator managed Ingress (Traefik) + +To deploy a mesh ingress on Kubernetes cluster which has [Traefik Kubernetes Ingress provider](https://doc.traefik.io/traefik/providers/kubernetes-ingress/), create the AWXMeshIngress resource on the namespace where your AWX instance is running on. + +Note that by deploying following AWXMeshIngress, AWX Operator will generate IngressRouteTCP resource that has `websecure` as an `entryPoints`. If this does not satisfy your requirement, refer to [User managed Ingress section](#on-kubernetes-with-user-managed-ingress) and create an IngressRouteTCP resource manually. + +Example: + +```yaml +--- +apiVersion: awx.ansible.com/v1alpha1 +kind: AWXMeshIngress +metadata: + name: +spec: + deployment_name: + + ingress_type: IngressRouteTCP + ingress_controller: traefik + ingress_class_name: traefik + ingress_api_version: traefik.io/v1alpha1 + + external_hostname: +``` + +### On Kubernetes with User managed Ingress + +To deploy a mesh ingress on Kubernetes cluster, create the AWXMeshIngress resource on the namespace where your AWX instance is running on. + +Alternatively, if you wish to create your own Ingress resource, you can deploy a mesh ingress with `ingress_type` set to `none` and then manually create an Ingress resource with any configuration. + +In this case, the `external_hostname` is still required as it is used to generate the certificate that will be used by Receptor. + +Example: + +```yaml +--- +apiVersion: awx.ansible.com/v1alpha1 +kind: AWXMeshIngress +metadata: + name: +spec: + deployment_name: + + ingress_type: none # This line can be omitted since this is the default value + external_hostname: +``` + +The requirements for user managed Ingress resource are as follows: + +- Supports WebSocket +- SSL/TLS Passthrough enabled +- Accessible over port `443` +- Having the same hostname as `external_hostname` in the AWXMeshIngress resource +- Routing the traffic to port `27199` of the Service of the same name as the AWXMeshIngress resource + +These are example Ingress resources for NGINX and Traefik. + +```yaml +# Ingress for NGINX Ingress Controller +--- +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: + annotations: + nginx.ingress.kubernetes.io/ssl-passthrough: "true" +spec: + ingressClassName: nginx + rules: + - host: + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: + port: + number: 27199 +``` + +```yaml +# Ingress for Traefik Kubernetes Ingress provider +--- +apiVersion: traefik.io/v1alpha1 +kind: IngressRouteTCP +metadata: + name: +spec: + entryPoints: + - websecure + routes: + - match: HostSNI(``) + services: + - name: + port: 27199 + tls: + passthrough: true +``` ## Validating setup of Mesh Ingress -After AWXMeshIngress has been successfully created a new Instance with the same name will show up in AWX Instance UI +After AWXMeshIngress has been successfully created, a new Instance with the same name will be registered to AWX and will be visible on the Instance UI page ![mesh ingress instance on AWX UI](mesh-ingress-instance-on-awx-ui.png) @@ -57,92 +177,48 @@ In this example, the mesh ingress has two listener addresses: When selecting peer for new instance the mesh ingress instance should now be present as a option. ![peering to mesh ingress on awx ui](peering-to-mesh-ingress-on-awx-ui.png) -For more information about how to create external remote execution and hop node and configuring the mesh. See AWX Documentation on [Add a instance](https://ansible.readthedocs.io/projects/awx/en/latest/administration/instances.html#add-an-instance). +For more information about how to create external remote execution and hop nodes and configuring the mesh, see AWX Documentation on [Add a instance](https://ansible.readthedocs.io/projects/awx/en/latest/administration/instances.html#add-an-instance). -## AWXMeshIngress +## Custom Resource Definitions + +### AWXMeshIngress AWXMeshIngress controls the deployment and configuration of mesh ingress on AWX -- **apiVersion**: awx.ansible.com/v1alpha1 +| Name | Description | +| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`apiVersion`** | awx.ansible.com/v1alpha1 | +| **`kind`** | AWXMeshIngress | +| **`metadata`** ([ObjectMeta](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/object-meta/#ObjectMeta)) | Standard object's metadata. [More info](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata) | +| **`spec`** ([AWXMeshIngressSpec](#awxmeshingressspec)) | Spec is the desired state of the AWXMeshIngress. [More info](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status) | +| **`status`** ([AWXMeshIngressStatus](#awxmeshingressstatus)) | Status is the current state of the AWXMeshIngress. [More info](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status) | -- **kind**: AWXMeshIngress +#### AWXMeshIngressSpec -- **metadata**: ([ObjectMeta](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/object-meta/#ObjectMeta)) +AWXMeshIngressSpec is the description of the configuration for AWXMeshIngress. - Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata +| Name | Description | Default | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | +| **`deployment_name`** (string), required | Name of the AWX deployment to create the Mesh Ingress for. | `awx` | +| **`ingress_type`** (string) | Ingress type for ingress managed by the operator. Options: `none`, `Ingress`, `IngressRouteTCP`, `Route` | `Route` (on OpenShift), `none` (on Kubernetes) | +| **`external_hostname`** (string) | External hostname is an optional field used for specifying the external hostname defined in an [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/). This parameter is automatically generated on OpenShift | N/A | +| **`external_ipaddress`** (string) | External IP Address is an optional field used for specifying the external IP address defined in an [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) | N/A | +| **`ingress_api_version`** (string) | API Version for ingress managed by the operator. This parameter is ignored when `ingress_type` is `Route` | `networking.k8s.io/v1` | +| **`ingress_annotations`** (string) | Additional annotation on the ingress managed by the operator. This parameter is ignored when `ingress_type` is `Route` | `""` | +| **`ingress_controller`** (string) | Special configuration for specific Ingress Controllers. This parameter is ignored when `ingress_type` is `Route` | `""` | +| **`ingress_class_name`** (string) | The name of ingress class to use instead of the cluster default. see [IngressSpec](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/ingress-v1/#IngressSpec). This parameter is ignored when `ingress_type` is `Route` | `""` | -- **spec**: ([AWXMeshIngressSpec](#awxmeshingressspec)) - - spec is the desired state of the AWXMeshIngress. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -- **status**: ([AWXMeshIngressStatus](#awxmeshingressstatus)) - - status is the current state of the AWXMeshIngress. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status - -### AWXMeshIngressSpec - -AWXMeshIngress is the description of the configuration for AWXMeshIngress. - -- **deployment_name** (string), required - - Name of the AWX deployment to create the Mesh Ingress for. - -- **external_hostname** (string) - - External hostname is an optional field used for specifying the external hostname defined in an user managed [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) - -- **external_ipaddress** (string) - - External IP Address is an optional field used for specifying the external IP address defined in an user managed [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) - -- **ingress_type** (string) - - Ingress type for ingress managed by the operator - Options: - - none (default) - - Ingress - - IngressRouteTCP - - Route (default when deploy on OpenShift) - -- **ingress_api_version** (string) - - API Version for ingress managed by the operator - This parameter is ignored when ingress_type=Route - -- **ingress_annotations** (string) - - Annotation on the ingress managed by the operator - -- **ingress_class_name** (string) - - The name of ingress class to use instead of the cluster default. see [IngressSpec](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/ingress-v1/#IngressSpec) - This parameter is ignored when `ingress_type=Route` - -- **ingress_controller** (string) - - Special configuration for specific Ingress Controllers - This parameter is ignored when ingress_type=Route - -### AWXMeshIngressStatus +#### AWXMeshIngressStatus AWXMeshIngressStatus describe the current state of the AWXMeshIngress. -## AWXMeshIngressList +### AWXMeshIngressList AWXMeshIngressList is a collection of AWXMeshIngress. -- **items** ([AWXMeshIngress](#awxmeshingress)) - - items is the list of Ingress. - -- **apiVersion** (string) - - APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources - -- **kind** (string) - - Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds - -- **metadata** ([ListMeta](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/list-meta/#ListMeta)) - - Standard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata +| Name | Description | +| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`items`** ([AWXMeshIngress](#awxmeshingress)) | items is the list of Ingress. | +| **`apiVersion`** (string) | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More info](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) | +| **`kind`** (string) | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More info](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) | +| **`metadata`** ([ListMeta](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/list-meta/#ListMeta)) | Standard object's metadata. [More info](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata) |