From 962b08dec17fa3a7db3f135a53c41ba12bca0be1 Mon Sep 17 00:00:00 2001 From: Christopher Negus Date: Sun, 19 Mar 2023 19:36:35 +0000 Subject: [PATCH 1/8] Add Get Started and new config to docs --- docs/configure.md | 322 ++++++++++++++------------------------------- docs/getstarted.md | 232 ++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 333 insertions(+), 222 deletions(-) create mode 100644 docs/getstarted.md diff --git a/docs/configure.md b/docs/configure.md index 2f876885..3782331a 100644 --- a/docs/configure.md +++ b/docs/configure.md @@ -1,222 +1,100 @@ -# Using the AWS Gateway API Controller - -The first part of this section provides an example of setting up of service-to-service communications on a single cluster. -The second section extends that example by creating another inventory service on a second cluster on a different VPC, and spreading traffic to that service across the two clusters and VPCs. -Both clusters are created using `eksctl`, with both clusters created from the same account by the same cluster admin. - -## Set up single-cluster/VPC service-to-service communications - -This example creates a single cluster in a single VPC, then configures two routes (rates and inventory) and three services (parking, review, and inventory-1). The following figure illustrates this setup: - -![Single cluster/VPC service-to-service communications](images/example1.png) - -**Steps** - - **Set up Service-to-Service communications** - -1. Create the Kubernetes Gateway `my-hotel`: - ```bash - kubectl apply -f examples/my-hotel-gateway.yaml - ``` - ***Note*** - - By default, the gateway(lattice service network) is not associated with cluster's VPC. To associate a gateway(lattice service network) to VPC, gateway object must have following annotation. - - - apiVersion: gateway.networking.k8s.io/v1alpha2 - kind: Gateway - metadata: - name: my-hotel - annotations: - application-networking.k8s.aws/lattice-vpc-association: "true" - - -1. Verify that `my-hotel` gateway is created (this could take about five minutes): - ```bash - kubectl get gateway - ``` - ``` - NAME CLASS ADDRESS READY AGE - my-hotel amazon-vpc-lattice 7d12h - ``` -1. Once the gateway is created, find the VPC Lattice service network: - ```bash - kubectl get gateway my-hotel -o yaml - ``` - ``` - apiVersion: gateway.networking.k8s.io/v1alpha2 - kind: Gateway - ... - status: - conditions: - message: 'aws-gateway-arn: arn:aws:vpc-lattice:us-west-2:694065802095:servicenetwork/sn-0ab6bb70055929edd' - reason: Reconciled - status: "True" - ``` -1. Create the Kubernetes HTTPRoute rates for the parking service, review service, and HTTPRoute rate: - ```bash - kubectl apply -f examples/parking.yaml - kubectl apply -f examples/review.yaml - kubectl apply -f examples/rate-route-path.yaml - ``` -1. Create the Kubernetes HTTPRoute inventory (this could take about five minutes): - ```bash - kubectl apply -f examples/inventory-ver1.yaml - kubectl apply -f examples/inventory-route.yaml - ``` -1. Find out HTTPRoute's DNS name from HTTPRoute status: - ```bash - kubectl get httproute - ``` - ``` - NAME HOSTNAMES AGE - inventory 51s - rates 6m11s - ``` -1. List the route’s yaml file to see the DNS address (highlighted here on the `message` line): - - ```bash - kubectl get httproute inventory -o yaml - ``` - - ``` - apiVersion: gateway.networking.k8s.io/v1alpha2 - kind: HTTPRoute - metadata: - annotations: - application-networking.k8s.aws/lattice-assigned-domain-name: inventory-default-02fb06f1acdeb5b55.7d67968.vpc-lattice-svcs.us-west-2.on.aws - ... - ``` - - ```bash - kubectl get httproute rates inventory -o yaml - ``` - - ``` - apiVersion: v1 - items: - - apiVersion: gateway.networking.k8s.io/v1alpha2 - kind: HTTPRoute - metadata: - annotations: - application-networking.k8s.aws/lattice-assigned-domain-name: rates-default-0d38139624f20d213.7d67968.vpc-lattice-svcs.us-west-2.on.aws - ... - ``` - -**Check service connectivity** - -1. Check Service-Inventory Pod access for Service-Rates/parking or Service-Rates/review by execing into the pod, then curling each service. - ```bash - kubectl get pod - ``` - ``` - NAME READY STATUS RESTARTS AGE - inventory-ver1-7bb6989d9d-2p2hk 1/1 Running 0 7d13h - inventory-ver1-7bb6989d9d-464rk 1/1 Running 0 7d13h - parking-6cdcd5b4b4-bbzvt 1/1 Running 0 103m - parking-6cdcd5b4b4-g8dkb 1/1 Running 0 103m - review-5888566ff6-2plsj 1/1 Running 0 101m - review-5888566ff6-89fqk 1/1 Running 0 101m - ``` -1. Exec into an inventory pod to check connectivity to parking and review services: - ```bash - kubectl exec -ti inventory-ver1-7bb6989d9d-2p2hk sh - ``` -1. From inside of the inventory pod, use `curl` to connect to the parking service (using the DNS Name from the previous `kubectl get httproute` command): - ```bash - curl rates-default-0d38139624f20d213.7d67968.vpc-lattice-svcs.us-west-2.on.aws/parking - ``` - ``` - Requesting to Pod(parking-6cdcd5b4b4-g8dkb): parking handler pod - ``` -1. From inside of the pod, use `curl` to connect to the review service: - ```bash - curl rates-00422586e3362607e.7d67968.vpc-service-network-svcs.us-west-2.amazonaws.com/review - ``` - ``` - Requesting to Pod(review-5888566ff6-89fqk): review handler pod - ``` -1. Exit the pod: - ```bash - exit - ``` -1. Exec into a parking pod to check connectivity to the inventory-ver1 service: - ```bash - kubectl exec -ti parking-6cdcd5b4b4-bbzvt sh - ``` -1. From inside of the parking pod, use `curl` to connect to the inventory-ver1 service: - ```bash - curl inventory-default-02fb06f1acdeb5b55.7d67968.vpc-lattice-svcs.us-west-2.on.aws - ``` - ``` - Requesting to Pod(inventory-ver1-7bb6989d9d-2p2hk): inventory-ver1 handler pod - ``` -## Set up multi-cluster/multi-VPC service-to-service communications - -This sections builds on the previous section by migrating a Kubernetes service (HTTPRoute inventory) from one Kubernetes cluster to a different Kubernetes cluster. -For example, it will: - -* Migrate the Kubernetes inventory service from a Kubernetes v1.21 cluster to a Kubernetes v1.23 cluster in a different VPC. -* Scale up the Kubernetes inventory service to run it in another cluster (and another VPC) in addition to the current cluster. - -The following figure illustrates this: - -![Multiple clusters/VPCs service-to-service communications](images/example2.png) - -**Steps** - - **Set up inventory on a second cluster** - -1. Create a second cluster (using the same instructions used to create the first). - -1. Ensure you're using the second cluster profile. - ```bash - kubectl config get-contexts - ``` - If your profile is set to the first cluster, switch your credentials to use the second cluster: - ```bash - kubectl config use-context - ``` -1. Create a Kubernetes inventory-ver2 service in the second cluster: - ```bash - kubectl apply -f examples/inventory-ver2.yaml - ``` -1. Export this Kubernetes inventory-ver2 from the second cluster, so that it can be referenced by HTTPRoute in the other cluster: - ```bash - kubectl apply -f examples/inventory-ver2-export.yaml - ``` - **Switch back to the first cluster** - -1. Switch credentials back to the first cluster - ```bash - kubectl config use-context - ``` -1. Import the Kubernetes inventory-ver2 into first cluster: - ```bash - kubectl apply -f examples/inventory-ver2-import.yaml - ``` -1. Update the HTTPRoute inventory to route 10% traffic to the first cluster and 90% traffic to the second cluster: - ```bash - kubectl apply -f examples/inventory-route-bluegreen.yaml - ``` -1. Check the Service-Rates/parking pod access to Service-Inventory by execing into the parking pod: - ```bash - kubectl exec -ti parking-6cdcd5b4b4-bbzvt sh - ``` -1. From inside of the pod, use `curl` to connect to the inventory service: - - ```bash - for ((i=1;i<=30;i++)); do curl "inventory-default-0f89d8ff5e98400d0.7d67968.vpc-lattice-svcs.us-west-2.on.aws"; done - ``` - ``` - Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod <----> in 2nd cluster - Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod - Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod - Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod - Requsting to Pod(inventory-ver2-6dc74b45d8-95rsr): Inventory-ver1 handler pod <----> in 1st cluster - Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod - Requsting to Pod(inventory-ver2-6dc74b45d8-95rsr): Inventory-ver2 handler pod - Requsting to Pod(inventory-ver2-6dc74b45d8-95rsr): Inventory-ver2 handler pod - Requsting to Pod(inventory-ver1-74fc59977-wg8br): Inventory-ver1 handler pod.... - ``` - You can see that the traffic is distributed between *inventory-ver1* and *inventory-ver2* as expected. +# Configure the AWS Gateway API Controller + +Refer to this document to further configure your use of the AWS Gateway API Controller. +The features here build on the examples shown in [Get Started Using the AWS Gateway API Controller](getstarted.md). + +## Setting up HTTPs connections + +The Getting Started guide uses HTTP (insecure) communications by default. +Using the examples here, you can change that to HTTPS (secure) communications. +If you choose, you can further customize your HTTPS connections by adding custom domain names and certificates, as described below. + +### Securing Traffic using HTTPS + +By adding https to the amazon-vpc-lattice gateway, you can tell the listener to use HTTPs communications. +The following modifications to the `examples/my-hotel-gateway.yaml` file add HTTPs communications: + +``` +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: Gateway +metadata: + name: my-hotel + annotations: + application-networking.k8s.aws/lattice-vpc-association: "true" +spec: + gatewayClassName: amazon-vpc-lattice + listeners: + - name: http + protocol: HTTP + port: 80 + - name: https # Specify https listener + protocol: HTTPS # Specify HTTPS protocol + port: 443 # Specify communication on port 443 +... +``` +Next, the following modifications to the `examples/rate-route-path.yaml` file tell the `rates` HTTPRoute to use HTTPS for communications: + +``` +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: rates +spec: + parentRefs: + - name: my-hotel + sectionName: http + - name: my-hotel # Specify the parertRefs name + sectionName: https # Specify all traffic MUST use HTTPs + rules: +... +``` + +In this case, the VPC Lattice service automatically generates a managed ACM certificate and uses it for encryting client to service traffic. + +### Bring Your Own Certificate (BYOC) + +If you want to use a custom domain name along with its own certificate, you can: + +* Follow instructions on [Requesting a public certificate](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) and get an ACM certificate ARN. +* Add the ARN to the listener configuration as shown below. + +The following shows modifications to `examples/my-hotel.yaml` to add a custom certificate: +``` +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: Gateway +metadata: + name: my-hotel +spec: + gatewayClassName: amazon-vpc-lattice + listeners: + - name: http + protocol: HTTP + port: 80 + - name: https + protocol: HTTPS + port: 443 + - name: tls-with-custom-cert # Specify listener with custom certs + protocol: HTTPS # Specify HTTPS protocol + port: 443 # Specify communication on port 443 + tls: # Specify TLS configuration + mode: Terminate # Specify mode for TLS listener + options: # Specify certificate options + application-networking.k8s.aws/certificate-arn: arn:aws:acm:us-west-2::certificate/4555204d-07e1-43f0-a533-d02750f41545 +``` +Note that only `Terminate` mode is supported (Passthrough is not supported). + +Next, associate the HTTPRoute to the listener configuration you just configured: + +``` +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: rates +spec: + parentRefs: + - name: my-hotel + sectionName: http + - name: my-hotel # Specify parentRefs + sectionName: tls-with-custom-cert # Specify custom-defined certificate +... +``` diff --git a/docs/getstarted.md b/docs/getstarted.md new file mode 100644 index 00000000..bef34bb7 --- /dev/null +++ b/docs/getstarted.md @@ -0,0 +1,232 @@ +# Get Start Using the AWS Gateway API Controller + +Once you have [deployed the AWS Gateway API Controller](configure.md), this guide helps you get started using the controller. + +The first part of this section provides an example of setting up of service-to-service communications on a single cluster. +The second section extends that example by creating another inventory service on a second cluster on a different VPC, and spreading traffic to that service across the two clusters and VPCs. +Both clusters are created using `eksctl`, with both clusters created from the same account by the same cluster admin. + +Using these examples as a foundation, see the + +## Set up single-cluster/VPC service-to-service communications + +This example creates a single cluster in a single VPC, then configures two routes (rates and inventory) and three services (parking, review, and inventory-1). The following figure illustrates this setup: + +![Single cluster/VPC service-to-service communications](images/example1.png) + +**Steps** + + **Set up Service-to-Service communications** + +1. Create the Kubernetes Gateway `my-hotel`: + ```bash + kubectl apply -f examples/my-hotel-gateway.yaml + ``` + ***Note*** + + By default, the gateway (lattice service network) is not associated with cluster's VPC. To associate a gateway (lattice service network) to VPC, `my-hotel-gateway.yaml` includes the following annotation. + + + apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: Gateway + metadata: + name: my-hotel + annotations: + application-networking.k8s.aws/lattice-vpc-association: "true" + + +1. Verify that `my-hotel` gateway is created (this could take about five minutes): + ```bash + kubectl get gateway + ``` + ``` + NAME CLASS ADDRESS READY AGE + my-hotel amazon-vpc-lattice 7d12h + ``` +1. Once the gateway is created, find the VPC Lattice service network: + ```bash + kubectl get gateway my-hotel -o yaml + ``` + ``` + apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: Gateway + ... + status: + conditions: + message: 'aws-gateway-arn: arn:aws:vpc-lattice:us-west-2:694065802095:servicenetwork/sn-0ab6bb70055929edd' + reason: Reconciled + status: "True" + type: Schedules + ``` +1. Create the Kubernetes HTTPRoute rates for the parking service, review service, and HTTPRoute rate: + ```bash + kubectl apply -f examples/parking.yaml + kubectl apply -f examples/review.yaml + kubectl apply -f examples/rate-route-path.yaml + ``` +1. Create the Kubernetes HTTPRoute inventory (this could take about five minutes): + ```bash + kubectl apply -f examples/inventory-ver1.yaml + kubectl apply -f examples/inventory-route.yaml + ``` +1. Find out HTTPRoute's DNS name from HTTPRoute status: + ```bash + kubectl get httproute + ``` + ``` + NAME HOSTNAMES AGE + inventory 51s + rates 6m11s + ``` +1. List the route’s yaml file to see the DNS address (highlighted here on the `message` line): + + ```bash + kubectl get httproute inventory -o yaml + ``` + + ``` + apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: HTTPRoute + metadata: + annotations: + application-networking.k8s.aws/lattice-assigned-domain-name: inventory-default-02fb06f1acdeb5b55.7d67968.vpc-lattice-svcs.us-west-2.on.aws + ... + ``` + + ```bash + kubectl get httproute rates -o yaml + ``` + + ``` + apiVersion: v1 + items: + - apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: HTTPRoute + metadata: + annotations: + application-networking.k8s.aws/lattice-assigned-domain-name: rates-default-0d38139624f20d213.7d67968.vpc-lattice-svcs.us-west-2.on.aws + ... + ``` + +**Check service connectivity** + +1. Check Service-Inventory Pod access for Service-Rates/parking or Service-Rates/review by execing into the pod, then curling each service. + ```bash + kubectl get pod + ``` + ``` + NAME READY STATUS RESTARTS AGE + inventory-ver1-7bb6989d9d-2p2hk 1/1 Running 0 7d13h + inventory-ver1-7bb6989d9d-464rk 1/1 Running 0 7d13h + parking-6cdcd5b4b4-bbzvt 1/1 Running 0 103m + parking-6cdcd5b4b4-g8dkb 1/1 Running 0 103m + review-5888566ff6-2plsj 1/1 Running 0 101m + review-5888566ff6-89fqk 1/1 Running 0 101m + ``` +1. Exec into an inventory pod to check connectivity to parking and review services: + ```bash + kubectl exec -ti inventory-ver1-7bb6989d9d-2p2hk sh + ``` +1. From inside of the inventory pod, use `curl` to connect to the parking service (using the DNS Name from the previous `kubectl get httproute` command): + ```bash + curl rates-default-0d38139624f20d213.7d67968.vpc-lattice-svcs.us-west-2.on.aws/parking + ``` + ``` + Requesting to Pod(parking-6cdcd5b4b4-g8dkb): parking handler pod + ``` +1. From inside of the pod, use `curl` to connect to the review service: + ```bash + curl rates-00422586e3362607e.7d67968.vpc-service-network-svcs.us-west-2.amazonaws.com/review + ``` + ``` + Requesting to Pod(review-5888566ff6-89fqk): review handler pod + ``` +1. Exit the pod: + ```bash + exit + ``` +1. Exec into a parking pod to check connectivity to the inventory-ver1 service: + ```bash + kubectl exec -ti parking-6cdcd5b4b4-bbzvt sh + ``` +1. From inside of the parking pod, use `curl` to connect to the inventory-ver1 service: + ```bash + curl inventory-default-02fb06f1acdeb5b55.7d67968.vpc-lattice-svcs.us-west-2.on.aws + ``` + ``` + Requesting to Pod(inventory-ver1-7bb6989d9d-2p2hk): inventory-ver1 handler pod + ``` +1. Exit the pod: + ```bash + exit + ``` + +## Set up multi-cluster/multi-VPC service-to-service communications + +This sections builds on the previous section by migrating a Kubernetes service (HTTPRoute inventory) from one Kubernetes cluster to a different Kubernetes cluster. +For example, it will: + +* Migrate the Kubernetes inventory service from a Kubernetes v1.21 cluster to a Kubernetes v1.23 cluster in a different VPC. +* Scale up the Kubernetes inventory service to run it in another cluster (and another VPC) in addition to the current cluster. + +The following figure illustrates this: + +![Multiple clusters/VPCs service-to-service communications](images/example2.png) + +**Steps** + + **Set up inventory on a second cluster** + +1. Create a second cluster (using the same instructions used to create the first). + +1. Ensure you're using the second cluster profile. + ```bash + kubectl config get-contexts + ``` + If your profile is set to the first cluster, switch your credentials to use the second cluster: + ```bash + kubectl config use-context + ``` +1. Create a Kubernetes inventory-ver2 service in the second cluster: + ```bash + kubectl apply -f examples/inventory-ver2.yaml + ``` +1. Export this Kubernetes inventory-ver2 from the second cluster, so that it can be referenced by HTTPRoute in the other cluster: + ```bash + kubectl apply -f examples/inventory-ver2-export.yaml + ``` + **Switch back to the first cluster** + +1. Switch credentials back to the first cluster + ```bash + kubectl config use-context + ``` +1. Import the Kubernetes inventory-ver2 into first cluster: + ```bash + kubectl apply -f examples/inventory-ver2-import.yaml + ``` +1. Update the HTTPRoute inventory to route 10% traffic to the first cluster and 90% traffic to the second cluster: + ```bash + kubectl apply -f examples/inventory-route-bluegreen.yaml + ``` +1. Check the Service-Rates/parking pod access to Service-Inventory by execing into the parking pod: + ```bash + kubectl exec -ti parking-6cdcd5b4b4-bbzvt sh + ``` +1. From inside of the pod, use `curl` to connect to the inventory service: + + ```bash + for ((i=1;i<=30;i++)); do curl "inventory-default-0f89d8ff5e98400d0.7d67968.vpc-lattice-svcs.us-west-2.on.aws"; done + ``` + ``` + Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod <----> in 2nd cluster + Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod + Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod + Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod + Requsting to Pod(inventory-ver2-6dc74b45d8-95rsr): Inventory-ver1 handler pod <----> in 1st cluster + Requsting to Pod(inventory-ver2-6dc74b45d8-rlnlt): Inventory-ver2 handler pod + Requsting to Pod(inventory-ver2-6dc74b45d8-95rsr): Inventory-ver2 handler pod + Requsting to Pod(inventory-ver2-6dc74b45d8-95rsr): Inventory-ver2 handler pod + Requsting to Pod(inventory-ver1-74fc59977-wg8br): Inventory-ver1 handler pod.... + ``` + You can see that the traffic is distributed between *inventory-ver1* and *inventory-ver2* as expected. diff --git a/mkdocs.yml b/mkdocs.yml index ebd697b9..00db9c4a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,6 +8,7 @@ strict: true nav: - Home: index.md - Deployment: deploy.md + - Get Started: getstarted.md - Configuration: configure.md - Design Overview: overview.md From 69fae970b5d9dc73cf116ffb635b4fe8d296eb83 Mon Sep 17 00:00:00 2001 From: Christopher Negus Date: Mon, 20 Mar 2023 17:56:50 +0000 Subject: [PATCH 2/8] Updated alpha to beta --- docs/customer_domain_name.md | 4 +- docs/getstarted.md | 8 +-- docs/https_byoc.md | 113 ----------------------------------- 3 files changed, 6 insertions(+), 119 deletions(-) delete mode 100644 docs/https_byoc.md diff --git a/docs/customer_domain_name.md b/docs/customer_domain_name.md index d6dd20ae..6fd4353b 100644 --- a/docs/customer_domain_name.md +++ b/docs/customer_domain_name.md @@ -4,7 +4,7 @@ Today when you create a HTTPRoute using `amazon-vpc-lattice` gatewayclass, Latti If you'd prefer to use a custom domain name for a HTTPRoute, you can specify them in hostname field of HTTPRoute. Here is one example ``` -apiVersion: gateway.networking.k8s.io/v1alpha2 +apiVersion: gateway.networking.k8s.io/v1beta1 kind: HTTPRoute metadata: name: review @@ -30,4 +30,4 @@ spec: * You MUST have a registered domain name (e.g. `my-test.com`) in route53 and complete the `Prerequisites` mentioned in [TODO - public BYOC doc](http://dev-dsk-tnmat-1d-8836d755.us-east-1.amazon.com/mercury/build/AWSMercuryDocs/AWSMercuryDocs-3.0/AL2_x86_64/DEV.STD.PTHREAD/build/server-root/vpc-lattice/latest/ug/service-custom-domain-name.html#dns-associate-custom) -* In addition, you NEED to manually associate your custom domain name with your service following [TODO - public BYOC doc](http://dev-dsk-tnmat-1d-8836d755.us-east-1.amazon.com/mercury/build/AWSMercuryDocs/AWSMercuryDocs-3.0/AL2_x86_64/DEV.STD.PTHREAD/build/server-root/vpc-lattice/latest/ug/service-custom-domain-name.html#dns-associate-custom). We do have [github issue](https://github.com/aws/aws-application-networking-k8s/issues/88), an enhancement request, to automate this process \ No newline at end of file +* In addition, you NEED to manually associate your custom domain name with your service following [TODO - public BYOC doc](http://dev-dsk-tnmat-1d-8836d755.us-east-1.amazon.com/mercury/build/AWSMercuryDocs/AWSMercuryDocs-3.0/AL2_x86_64/DEV.STD.PTHREAD/build/server-root/vpc-lattice/latest/ug/service-custom-domain-name.html#dns-associate-custom). We do have [github issue](https://github.com/aws/aws-application-networking-k8s/issues/88), an enhancement request, to automate this process diff --git a/docs/getstarted.md b/docs/getstarted.md index bef34bb7..8d36401d 100644 --- a/docs/getstarted.md +++ b/docs/getstarted.md @@ -27,7 +27,7 @@ This example creates a single cluster in a single VPC, then configures two route By default, the gateway (lattice service network) is not associated with cluster's VPC. To associate a gateway (lattice service network) to VPC, `my-hotel-gateway.yaml` includes the following annotation. - apiVersion: gateway.networking.k8s.io/v1alpha2 + apiVersion: gateway.networking.k8s.io/v1beta1 kind: Gateway metadata: name: my-hotel @@ -48,7 +48,7 @@ This example creates a single cluster in a single VPC, then configures two route kubectl get gateway my-hotel -o yaml ``` ``` - apiVersion: gateway.networking.k8s.io/v1alpha2 + apiVersion: gateway.networking.k8s.io/v1beta1 kind: Gateway ... status: @@ -85,7 +85,7 @@ This example creates a single cluster in a single VPC, then configures two route ``` ``` - apiVersion: gateway.networking.k8s.io/v1alpha2 + apiVersion: gateway.networking.k8s.io/v1beta1 kind: HTTPRoute metadata: annotations: @@ -100,7 +100,7 @@ This example creates a single cluster in a single VPC, then configures two route ``` apiVersion: v1 items: - - apiVersion: gateway.networking.k8s.io/v1alpha2 + - apiVersion: gateway.networking.k8s.io/v1beta1 kind: HTTPRoute metadata: annotations: diff --git a/docs/https_byoc.md b/docs/https_byoc.md deleted file mode 100644 index c61a2736..00000000 --- a/docs/https_byoc.md +++ /dev/null @@ -1,113 +0,0 @@ -# HTTPS and Bring Your Own Certificte (BYOC) -## Securing Traffic using HTTPS - -Today, the HTTPRoute owner can specify all incoming traffic `MUST` use HTTPs. e.g. - -``` -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: Gateway -metadata: - name: my-hotel -spec: - gatewayClassName: amazon-vpc-lattice - listeners: - - name: http - protocol: HTTP - port: 80 - - name: https <-------------- specify HTTPs listener - protocol: HTTPS - port: 443 -``` - -``` -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: HTTPRoute -metadata: - name: rates -spec: - parentRefs: - - name: my-hotel - sectionName: http - - name: my-hotel - sectionName: https <--- specify all traffic MUST use HTTPs - rules: - - backendRefs: - - name: parking - kind: Service - port: 8090 - matches: - - path: - type: PathPrefix - value: /parking - - backendRefs: - - name: review - kind: Service - port: 8090 - matches: - - path: - type: PathPrefix - value: /review -``` - -In this case, VPC Lattice service will automatically generate a managed ACM certificate and use it for encryting client to service traffic. - -## Bring Your Own Certificate (BYOC) - -If customer desires to use custom domain name along with their own certificate, they can do following: -* follow [TODO Bring Your Own Certicate DOC](http://dev-dsk-tnmat-1d-8836d755.us-east-1.amazon.com/mercury/build/AWSMercuryDocs/AWSMercuryDocs-3.0/AL2_x86_64/DEV.STD.PTHREAD/build/server-root/vpc-lattice/latest/ug/service-byoc.html), and get ACM certificate ARN -* specify certificate ARN - -``` -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: Gateway -metadata: - name: my-hotel -spec: - gatewayClassName: amazon-vpc-lattice - listeners: - - name: http - protocol: HTTP - port: 80 - - name: https - protocol: HTTPS - port: 443 - - name: rates-with-custom-cert - protocol: HTTPS - port: 443 - tls: - mode: Terminate - options: - application-networking.k8s.aws/certificate-arn: arn:aws:acm:us-west-2::certificate/4555204d-07e1-43f0-a533-d02750f41545 -``` - -* associate HTTPRoute to this - -``` -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: HTTPRoute -metadata: - name: rates -spec: - parentRefs: - - name: my-hotel - sectionName: http - - name: my-hotel - sectionName: rates-with-custom-cert <-----using custom defined certification - rules: - - backendRefs: - - name: parking - kind: Service - port: 8090 - matches: - - path: - type: PathPrefix - value: /parking - - backendRefs: - - name: review - kind: Service - port: 8090 - matches: - - path: - type: PathPrefix - value: /review -``` \ No newline at end of file From ded8f9cba15aa461a8acbdae08059729a93737db Mon Sep 17 00:00:00 2001 From: Christopher Negus Date: Mon, 20 Mar 2023 18:21:39 +0000 Subject: [PATCH 3/8] Moved config information into its own folder --- docs/configure/health.md | 3 +++ docs/{configure.md => configure/https.md} | 7 +------ docs/{ => configure}/index.md | 0 mkdocs.yml | 5 ++++- 4 files changed, 8 insertions(+), 7 deletions(-) create mode 100644 docs/configure/health.md rename docs/{configure.md => configure/https.md} (92%) rename docs/{ => configure}/index.md (100%) diff --git a/docs/configure/health.md b/docs/configure/health.md new file mode 100644 index 00000000..97a91d69 --- /dev/null +++ b/docs/configure/health.md @@ -0,0 +1,3 @@ +## Configure Pod Health Checks + +Add Pod health check information here. diff --git a/docs/configure.md b/docs/configure/https.md similarity index 92% rename from docs/configure.md rename to docs/configure/https.md index 3782331a..d8931ad0 100644 --- a/docs/configure.md +++ b/docs/configure/https.md @@ -1,9 +1,4 @@ -# Configure the AWS Gateway API Controller - -Refer to this document to further configure your use of the AWS Gateway API Controller. -The features here build on the examples shown in [Get Started Using the AWS Gateway API Controller](getstarted.md). - -## Setting up HTTPs connections +## Configure HTTPs connections The Getting Started guide uses HTTP (insecure) communications by default. Using the examples here, you can change that to HTTPS (secure) communications. diff --git a/docs/index.md b/docs/configure/index.md similarity index 100% rename from docs/index.md rename to docs/configure/index.md diff --git a/mkdocs.yml b/mkdocs.yml index 00db9c4a..156a1a6d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,7 +9,10 @@ nav: - Home: index.md - Deployment: deploy.md - Get Started: getstarted.md - - Configuration: configure.md + - Configuration: + - Overview: configure/index.md + - Configure HTTPs: https.md + - Configure Healthchecks: health.md - Design Overview: overview.md plugins: From bfe19e262ec2fd0b0cc9d9ae79a303e9e0e762ee Mon Sep 17 00:00:00 2001 From: Christopher Negus Date: Mon, 20 Mar 2023 18:28:17 +0000 Subject: [PATCH 4/8] Fixed mkdocs.yml with new config directory --- mkdocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 156a1a6d..a259512c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,8 +11,8 @@ nav: - Get Started: getstarted.md - Configuration: - Overview: configure/index.md - - Configure HTTPs: https.md - - Configure Healthchecks: health.md + - Configure HTTPs: configure/https.md + - Configure Healthchecks: configure/health.md - Design Overview: overview.md plugins: From 8be17621ee243a371789954229e17cca1ac26ff1 Mon Sep 17 00:00:00 2001 From: Christopher Negus Date: Mon, 20 Mar 2023 18:35:41 +0000 Subject: [PATCH 5/8] Moved some files. --- docs/configure/index.md | 26 ++------------------------ docs/customer_domain_name.md | 33 --------------------------------- docs/index.md | 24 ++++++++++++++++++++++++ 3 files changed, 26 insertions(+), 57 deletions(-) delete mode 100644 docs/customer_domain_name.md create mode 100644 docs/index.md diff --git a/docs/configure/index.md b/docs/configure/index.md index 0c6bcfe3..c75abb3f 100644 --- a/docs/configure/index.md +++ b/docs/configure/index.md @@ -1,24 +1,2 @@ -# AWS Gateway API Controller User Guide - -The AWS Gateway API Controller lets you connect services across multiple Kubernetes clusters through the Kubernetes Gateway API interface. -It is also designed to connect services running on EC2 instances, containers, and as serverless functions. -It does this by leveraging Amazon VPC Lattice, which works with Kubernetes Gateway API calls to manage Kubernetes objects. - -This document describes how to set up the AWS Gateway API Controller and provides example use cases. -With the controller deployed and running, you will be able to manage services for multiple Kubernetes clusters and other targets on AWS through the following: - -* **CLI**: Use `aws` and `eksctl` to create clusters and set up AWS policies. Then use `kubectl` and YAML files to set up Kubernetes objects. -* **AWS Console**: View VPC Lattice assets through the VPC area of the AWS console. - -While separating the application developer from the details of the underling infrastructure, the controller also provides a Kubernetes-native experience, rather than creating a lot of new AWS ways of managing services. -It does this by integrating with the Kubernetes Gateway API. -This lets you work with Kubernetes service-related resources using Kubernetes APIs and custom resource definitions (CRDs) defined by the Kubernetes [networking.k8s.io specification](https://gateway-api.sigs.k8s.io/references/spec/). - -For more information on this technology, see [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/). - -A few things to keep in mind: - -* If you are new to the VPC Lattice service, keep in mind that names you use for objects must be unique across your entire account and not just across each cluster used by that account. -* Your AWS CNI must be v1.8.0 or later to work with VPC Lattice. - - +# Configure AWS Gateway API Controller +Use the content here to further configure the AWS Gateway API Controller. diff --git a/docs/customer_domain_name.md b/docs/customer_domain_name.md deleted file mode 100644 index 6fd4353b..00000000 --- a/docs/customer_domain_name.md +++ /dev/null @@ -1,33 +0,0 @@ -# Configure a Custom Domain Name for HTTPRoute -Today when you create a HTTPRoute using `amazon-vpc-lattice` gatewayclass, Lattice gateway-api-controller creates a AWS VPC Lattice Service during reconciliation. And VPC Lattice generates a unique Fully Qualified Domain Name (FQDN). However, this VPC Lattice generated domain name is not easy for customers to remember and use. - -If you'd prefer to use a custom domain name for a HTTPRoute, you can specify them in hostname field of HTTPRoute. Here is one example - -``` -apiVersion: gateway.networking.k8s.io/v1beta1 -kind: HTTPRoute -metadata: - name: review -spec: - hostnames: - - review.my-test.com <----------- this is the custom domain name - parentRefs: - - name: my-hotel - sectionName: http - rules: - - backendRefs: - - name: review2 - kind: Service - port: 8090 - matches: - - path: - type: PathPrefix - value: /review2 - -``` - -## Notes - -* You MUST have a registered domain name (e.g. `my-test.com`) in route53 and complete the `Prerequisites` mentioned in [TODO - public BYOC doc](http://dev-dsk-tnmat-1d-8836d755.us-east-1.amazon.com/mercury/build/AWSMercuryDocs/AWSMercuryDocs-3.0/AL2_x86_64/DEV.STD.PTHREAD/build/server-root/vpc-lattice/latest/ug/service-custom-domain-name.html#dns-associate-custom) - -* In addition, you NEED to manually associate your custom domain name with your service following [TODO - public BYOC doc](http://dev-dsk-tnmat-1d-8836d755.us-east-1.amazon.com/mercury/build/AWSMercuryDocs/AWSMercuryDocs-3.0/AL2_x86_64/DEV.STD.PTHREAD/build/server-root/vpc-lattice/latest/ug/service-custom-domain-name.html#dns-associate-custom). We do have [github issue](https://github.com/aws/aws-application-networking-k8s/issues/88), an enhancement request, to automate this process diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..0c6bcfe3 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,24 @@ +# AWS Gateway API Controller User Guide + +The AWS Gateway API Controller lets you connect services across multiple Kubernetes clusters through the Kubernetes Gateway API interface. +It is also designed to connect services running on EC2 instances, containers, and as serverless functions. +It does this by leveraging Amazon VPC Lattice, which works with Kubernetes Gateway API calls to manage Kubernetes objects. + +This document describes how to set up the AWS Gateway API Controller and provides example use cases. +With the controller deployed and running, you will be able to manage services for multiple Kubernetes clusters and other targets on AWS through the following: + +* **CLI**: Use `aws` and `eksctl` to create clusters and set up AWS policies. Then use `kubectl` and YAML files to set up Kubernetes objects. +* **AWS Console**: View VPC Lattice assets through the VPC area of the AWS console. + +While separating the application developer from the details of the underling infrastructure, the controller also provides a Kubernetes-native experience, rather than creating a lot of new AWS ways of managing services. +It does this by integrating with the Kubernetes Gateway API. +This lets you work with Kubernetes service-related resources using Kubernetes APIs and custom resource definitions (CRDs) defined by the Kubernetes [networking.k8s.io specification](https://gateway-api.sigs.k8s.io/references/spec/). + +For more information on this technology, see [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/). + +A few things to keep in mind: + +* If you are new to the VPC Lattice service, keep in mind that names you use for objects must be unique across your entire account and not just across each cluster used by that account. +* Your AWS CNI must be v1.8.0 or later to work with VPC Lattice. + + From 058dcb0b61c73a7c3697cbb491cbf5e4820f2b5f Mon Sep 17 00:00:00 2001 From: Christopher Negus Date: Mon, 20 Mar 2023 18:41:13 +0000 Subject: [PATCH 6/8] Added some text to config section --- docs/configure/health.md | 3 --- docs/configure/index.md | 3 ++- 2 files changed, 2 insertions(+), 4 deletions(-) delete mode 100644 docs/configure/health.md diff --git a/docs/configure/health.md b/docs/configure/health.md deleted file mode 100644 index 97a91d69..00000000 --- a/docs/configure/health.md +++ /dev/null @@ -1,3 +0,0 @@ -## Configure Pod Health Checks - -Add Pod health check information here. diff --git a/docs/configure/index.md b/docs/configure/index.md index c75abb3f..7c711be6 100644 --- a/docs/configure/index.md +++ b/docs/configure/index.md @@ -1,2 +1,3 @@ # Configure AWS Gateway API Controller -Use the content here to further configure the AWS Gateway API Controller. +Refer to this document to further configure your use of the AWS Gateway API Controller. +The features here build on the examples shown in [Get Started Using the AWS Gateway API Controller](getstarted.md). From 27ebd71698f71542ad9468b41d4514e3c1819ce7 Mon Sep 17 00:00:00 2001 From: Christopher Negus Date: Mon, 20 Mar 2023 18:48:00 +0000 Subject: [PATCH 7/8] Added customer_domain_name file --- docs/configure/customer_domain_name.md | 33 ++++++++++++++++++++++++++ mkdocs.yml | 2 +- 2 files changed, 34 insertions(+), 1 deletion(-) create mode 100644 docs/configure/customer_domain_name.md diff --git a/docs/configure/customer_domain_name.md b/docs/configure/customer_domain_name.md new file mode 100644 index 00000000..a299f201 --- /dev/null +++ b/docs/configure/customer_domain_name.md @@ -0,0 +1,33 @@ +# Configure a Custom Domain Name for HTTPRoute +Today when you create a HTTPRoute using `amazon-vpc-lattice` gatewayclass, Lattice gateway-api-controller creates a AWS VPC Lattice Service during reconciliation. And VPC Lattice generates a unique Fully Qualified Domain Name (FQDN). However, this VPC Lattice generated domain name is not easy for customers to remember and use. + +If you'd prefer to use a custom domain name for a HTTPRoute, you can specify them in hostname field of HTTPRoute. Here is one example + +``` +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: HTTPRoute +metadata: + name: review +spec: + hostnames: + - review.my-test.com <----------- this is the custom domain name + parentRefs: + - name: my-hotel + sectionName: http + rules: + - backendRefs: + - name: review2 + kind: Service + port: 8090 + matches: + - path: + type: PathPrefix + value: /review2 + +``` + +## Notes + +* You MUST have a registered domain name (e.g. `my-test.com`) in route53 and complete the `Prerequisites` mentioned in [TODO - public BYOC doc](http://dev-dsk-tnmat-1d-8836d755.us-east-1.amazon.com/mercury/build/AWSMercuryDocs/AWSMercuryDocs-3.0/AL2_x86_64/DEV.STD.PTHREAD/build/server-root/vpc-lattice/latest/ug/service-custom-domain-name.html#dns-associate-custom) + +* In addition, you NEED to manually associate your custom domain name with your service following [TODO - public BYOC doc](http://dev-dsk-tnmat-1d-8836d755.us-east-1.amazon.com/mercury/build/AWSMercuryDocs/AWSMercuryDocs-3.0/AL2_x86_64/DEV.STD.PTHREAD/build/server-root/vpc-lattice/latest/ug/service-custom-domain-name.html#dns-associate-custom). We do have [github issue](https://github.co diff --git a/mkdocs.yml b/mkdocs.yml index a259512c..d4b675d5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,7 +12,7 @@ nav: - Configuration: - Overview: configure/index.md - Configure HTTPs: configure/https.md - - Configure Healthchecks: configure/health.md + - Configure domain name: configure/customer_domain_name.md - Design Overview: overview.md plugins: From d10e8571f2c81e285ac094fba9ed6208771f9c76 Mon Sep 17 00:00:00 2001 From: Christopher Negus Date: Mon, 20 Mar 2023 19:00:19 +0000 Subject: [PATCH 8/8] Added hostname to https file --- docs/configure/https.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/configure/https.md b/docs/configure/https.md index d8931ad0..e7af25b6 100644 --- a/docs/configure/https.md +++ b/docs/configure/https.md @@ -86,6 +86,8 @@ kind: HTTPRoute metadata: name: rates spec: + hostnames: + - review.my-test.com # MUST match the DNS in the certificate parentRefs: - name: my-hotel sectionName: http