diff --git a/docs/customer_domain_name.md b/docs/configure/customer_domain_name.md similarity index 94% rename from docs/customer_domain_name.md rename to docs/configure/customer_domain_name.md index d6dd20ae..a299f201 100644 --- a/docs/customer_domain_name.md +++ b/docs/configure/customer_domain_name.md @@ -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.co diff --git a/docs/configure/https.md b/docs/configure/https.md new file mode 100644 index 00000000..e7af25b6 --- /dev/null +++ b/docs/configure/https.md @@ -0,0 +1,97 @@ +## 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. +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: + hostnames: + - review.my-test.com # MUST match the DNS in the certificate + parentRefs: + - name: my-hotel + sectionName: http + - name: my-hotel # Specify parentRefs + sectionName: tls-with-custom-cert # Specify custom-defined certificate +... +``` diff --git a/docs/configure/index.md b/docs/configure/index.md new file mode 100644 index 00000000..7c711be6 --- /dev/null +++ b/docs/configure/index.md @@ -0,0 +1,3 @@ +# Configure 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). diff --git a/docs/configure.md b/docs/getstarted.md similarity index 91% rename from docs/configure.md rename to docs/getstarted.md index 2f876885..8d36401d 100644 --- a/docs/configure.md +++ b/docs/getstarted.md @@ -1,9 +1,13 @@ -# Using the AWS Gateway API Controller +# 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: @@ -20,10 +24,10 @@ This example creates a single cluster in a single VPC, then configures two route ``` ***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. + 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 @@ -44,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: @@ -52,6 +56,7 @@ This example creates a single cluster in a single VPC, then configures two route 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 @@ -80,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: @@ -89,13 +94,13 @@ This example creates a single cluster in a single VPC, then configures two route ``` ```bash - kubectl get httproute rates inventory -o yaml + kubectl get httproute rates -o yaml ``` ``` apiVersion: v1 items: - - apiVersion: gateway.networking.k8s.io/v1alpha2 + - apiVersion: gateway.networking.k8s.io/v1beta1 kind: HTTPRoute metadata: annotations: @@ -151,6 +156,11 @@ This example creates a single cluster in a single VPC, then configures two route ``` 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. 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 diff --git a/mkdocs.yml b/mkdocs.yml index ebd697b9..d4b675d5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,7 +8,11 @@ strict: true nav: - Home: index.md - Deployment: deploy.md - - Configuration: configure.md + - Get Started: getstarted.md + - Configuration: + - Overview: configure/index.md + - Configure HTTPs: configure/https.md + - Configure domain name: configure/customer_domain_name.md - Design Overview: overview.md plugins: