From 27206d9202fe23e88c0814adea4b43180d23d495 Mon Sep 17 00:00:00 2001
From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Date: Mon, 12 Jun 2023 13:41:16 -0700
Subject: [PATCH] CAPIgw for K8s installation updates for 1.16 (#17627)

* trimmed CRD step and reqs from installation

* updated tech specs

* Apply suggestions from code review

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Co-authored-by: Jeff Apple <79924108+Jeff-Apple@users.noreply.github.com>

* added upgrade instruction

* removed tcp port req

* described downtime and DT-less upgrades

* applied additional review feedback

---------

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
Co-authored-by: Jeff Apple <79924108+Jeff-Apple@users.noreply.github.com>
---
 .../api-gateway/configuration/gateway.mdx     |  2 +-
 website/content/docs/api-gateway/install.mdx  | 79 ++++++---------
 .../content/docs/api-gateway/tech-specs.mdx   | 45 ++++-----
 website/content/docs/api-gateway/upgrades.mdx | 99 ++++++++++++++++++-
 4 files changed, 147 insertions(+), 78 deletions(-)

diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx
index 9d9b87b3b7..fdbe468ba8 100644
--- a/website/content/docs/api-gateway/configuration/gateway.mdx
+++ b/website/content/docs/api-gateway/configuration/gateway.mdx
@@ -58,7 +58,7 @@ The following outline shows how to format the configurations in the `Gateway` ob
 This topic provides details about the configuration parameters.
 
 ### gatewayClassName
-Specifies the name of the [`GatewayClass`](/consul/docs/api-gateway/configuration/gatewayclass) resource used for the `Gateway` instance. Unless you are using a custom [GatewayClass](/consul/docs/api-gateway/configuration/gatewayclass), this value should be set to `consul-api-gateway`.
+Specifies the name of the [`GatewayClass`](/consul/docs/api-gateway/configuration/gatewayclass) resource used for the `Gateway` instance. Unless you are using a custom [GatewayClass](/consul/docs/api-gateway/configuration/gatewayclass), this value should be set to `consul`.
 * Type: string
 * Required: required
 
diff --git a/website/content/docs/api-gateway/install.mdx b/website/content/docs/api-gateway/install.mdx
index 1d715c0c47..6285c9525a 100644
--- a/website/content/docs/api-gateway/install.mdx
+++ b/website/content/docs/api-gateway/install.mdx
@@ -5,29 +5,11 @@ description: >-
   Learn how to install custom resource definitions (CRDs) and configure the Helm chart so that you can run Consul API Gateway on your Kubernetes deployment.
 ---
 
-# Install API Gateway for Kubernetes
+# Install API gateway for Kubernetes
 
-This topic describes how to install and configure Consul API Gateway.
+The Consul API gateway ships with Consul and is automatically installed when you install Consul on Kubernetes. Before you begin the installation process, verify that the environment you are deploying Consul and the API gateway in meets the requirements listed in the [Technical Specifications](/consul/docs/api-gateway/tech-specs). Refer to the [Release Notes](/consul/docs/release-notes) for any additional information about the version you are deploying.
 
-## Requirements
-
-Ensure that the environment you are deploying Consul API Gateway in meets the requirements listed in the [Technical Specifications][tech-specs]. This includes validating that the requirements for minimum versions of software are met. Refer to the [Release Notes][rel-notes] for the version of API Gateway you are deploying.
-
-## Installation
-
-1. Set the version of Consul API Gateway you are installing as an environment variable. The following steps use this environment variable in commands and configurations.
-
-  ```shell-session
-  $ export VERSION=0.5.1
-  ```
-
-1. Issue the following command to install the CRDs:
-
-  ```shell-session
-  $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v$VERSION"
-  ```
-
-1. Create a `values.yaml` file for your Consul API Gateway deployment by copying the following content and running it in the environment where you set the `VERSION` environment variable. The Consul Helm chart uses this `values.yaml` file to deploy the API Gateway. Available versions of the [Consul](https://hub.docker.com/r/hashicorp/consul/tags) and [Consul API Gateway](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags) Docker images can be found on DockerHub, with additional context on version compatibility published in [GitHub releases](https://github.com/hashicorp/consul-api-gateway/releases). For more options to configure your Consul API Gateway deployment through the Helm chart, refer to [Helm Chart Configuration - apiGateway](/consul/docs/k8s/helm#apigateway).
+1. Create a `values.yaml` file for configuring your Consul API gateway deployment and include the following settings:
 
     <CodeBlockConfig filename="values.yaml">
 
@@ -37,47 +19,46 @@ Ensure that the environment you are deploying Consul API Gateway in meets the re
             name: consul
           connectInject:
             enabled: true
-          apiGateway:
-            enabled: true
-            image: hashicorp/consul-api-gateway:$VERSION
         EOF
       ```
     </CodeBlockConfig>
 
-1. Install Consul API Gateway using the standard Consul Helm chart or Consul K8s CLI specify the custom values file. Available versions of the [Consul Helm chart](https://github.com/hashicorp/consul-k8s/releases) can be found in GitHub releases.
+  The Consul Helm chart deploys the API gateway using the configuration specified in the `values.yaml` file. Refer to [Helm Chart Configuration - `connectInject.apiGateway`](/consul/docs/k8s/helm#apigateway) for information about the Helm chart configuration options.
 
-  <Tabs>
-    <Tab heading="Consul K8s CLI (Mac Only)">
+1. Install Consul API Gateway using the standard Consul Helm chart or Consul K8s CLI specify the custom values file. Refer to the [Consul Helm chart](https://github.com/hashicorp/consul-k8s/releases) in GitHub releases for the available versions.
 
-    ~> **Note:** Refer to the official [Consul K8S CLI documentation](/consul/docs/k8s/k8s-cli) to find additional settings.
+<Tabs>
+<Tab heading="Consul K8s CLI (Mac Only)">
 
-    ```shell-session
-    $ brew tap hashicorp/tap
-    ```
+Refer to the official [Consul K8S CLI documentation](/consul/docs/k8s/k8s-cli) to find additional settings.
 
-    ```shell-session
-    $ brew install hashicorp/tap/consul-k8s
-    ```
+```shell-session
+$ brew tap hashicorp/tap
+```
 
-    ```shell-session
-    $ consul-k8s install -config-file=values.yaml -set global.image=hashicorp/consul:1.14.3
-    ```
+```shell-session
+$ brew install hashicorp/tap/consul-k8s
+```
 
-    </Tab>
-    <Tab heading="Helm">
+```shell-session
+$ consul-k8s install -config-file=values.yaml -set global.image=hashicorp/consul:1.16.0
+```
 
-    Add the HashiCorp Helm repository.
+</Tab>
+<Tab heading="Helm">
 
-    ```shell-session
-    $ helm repo add hashicorp https://helm.releases.hashicorp.com
-    ```
-    Install Consul with API Gateway on your Kubernetes cluster by specifying the `values.yaml` file.
+Add the HashiCorp Helm repository.
 
-    ```shell-session
-    $ helm install consul hashicorp/consul --version 1.0.2 --values values.yaml --create-namespace --namespace consul
-    ```
-    </Tab>
-  </Tabs>
+```shell-session
+$ helm repo add hashicorp https://helm.releases.hashicorp.com
+```
+Install Consul with API Gateway on your Kubernetes cluster by specifying the `values.yaml` file.
+
+```shell-session
+$ helm install consul hashicorp/consul --version 1.2.0 --values values.yaml --create-namespace --namespace consul
+```
+</Tab>
+</Tabs>
 
 <!--
 ****** KEEP ALL PAGE CONTENT ABOVE THIS LINE *******
diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx
index 7fb142340d..22fa8d30b5 100644
--- a/website/content/docs/api-gateway/tech-specs.mdx
+++ b/website/content/docs/api-gateway/tech-specs.mdx
@@ -1,40 +1,34 @@
 ---
 layout: docs
-page_title: API Gateway for Kubernetes Technical Specifications
+page_title: API gateway for Kubernetes technical specifications
 description: >-
-  Consul API Gateway is a service mesh add-on for Kubernetes deployments. Learn about its requirements for system resources, ports, and component versions, its Enterprise limitations, and compatible k8s cloud environments.
+  Learn about the requirements for installing and using the Consul API gateway for Kubernetes, including required ports, component version minimums, Consul Enterprise limitations, and compatible k8s cloud environments.
 ---
 
-# API Gateway for Kubernetes Technical Specifications
+# API gateway for Kubernetes technical specifications
 
-This topic describes the technical specifications associated with using Consul API Gateway.
+This topic describes the technical specifications associated with using Consul API gateway.
 
 ## Requirements
 
-Verify that your environment meets the following requirements prior to using Consul API Gateway.
+Verify that your environment meets the following requirements prior to using Consul API gateway.
 
-### Datacenter Requirements
+### Datacenter requirements
 
-Your datacenter must meet the following requirements prior to configuring the Consul API Gateway:
+Your datacenter must meet the following requirements prior to configuring the Consul API gateway:
 
-- Kubernetes 1.21+
-- `kubectl` 1.21+
-- Consul 1.11.2+
-- HashiCorp Consul Helm chart 0.47.1+
-- Consul Service Mesh must be deployed on the Kubernetes cluster that API Gateway is deployed on.
-- Envoy:  Envoy proxy support is determined by the Consul version deployed. Refer to [Envoy Integration](/consul/docs/connect/proxies/envoy) for details.
+- HashiCorp Consul Helm chart v1.2.0 and later
 
-### TCP Port Requirements
+### TCP port requirements
 
-The following table describes the TCP port requirements for each component of the API Gateway.
+The following table describes the TCP port requirements for each component of the API gateway.
 
 | Port | Description | Component |
 | ---- | ----------- | --------- |
-| 9090 | Secret discovery service (SDS) | Gateway controller pod <br/> Gateway instance pod |
 | 20000 | Kubernetes readiness probe | Gateway instance pod |
 | Configurable | Port for scraping Prometheus metrics. Disabled by default. | Gateway controller pod |
 
-## Consul Server Deployments
+## Consul server deployments
 
 - Consul Editions supported: OSS and Enterprise
 - Supported Consul Server deployment types:
@@ -43,36 +37,35 @@ The following table describes the TCP port requirements for each component of th
 
 ### Limited Support of some Consul Features
 
-The following table lists API Gateway limitations related to specific Consul features
+The following table lists API gateway limitations related to specific Consul features
 
 | Consul Feature | Limitation |
 | -------------- | ---------- |
-| [Admin partitions](/consul/docs/enterprise/admin-partitions) | You can deploy Consul API Gateway into the `default` admin partition only. You can route to services in other `default` admin partitions through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. |
 | Routing between datacenters | If you are connecting multiple Consul datacenters to create a federated network, you can route to services in other datacenters through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. |
 
 ## Deployment Environments
 
-Consul API Gateway can be deployed in the following Kubernetes-based environments:
+Consul API gateway can be deployed in the following Kubernetes-based environments:
 
 - Generic Kubernetes
 - AWS Elastic Kubernetes Service (EKS)
 - Google Kubernetes Engine (GKE)
 - Azure Kubernetes Service (AKS)
 
-## Kubernetes Gateway API Specification - Supported Versions
+## Supported versions of Kubernetes Gateway API specification 
 
-See the Release Notes for the version of Consul API Gateway being used.
+Refer to the [release notes](/consul/docs/release-notes) for your version of Consul.
 
-## Resource Allocations
+## Resource allocations
 
-The following resources are allocated for each component of the API Gateway.
+The following resources are allocated for each component of the API gateway.
 
-### Gateway Controller Pod
+### Gateway controller pod
 
 - **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
 - **Memory**: None. Either the the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
 
-### Gateway Instance Pod
+### Gateway instance pod
 
 - **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
 - **Memory**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
diff --git a/website/content/docs/api-gateway/upgrades.mdx b/website/content/docs/api-gateway/upgrades.mdx
index 373eeffcb1..d45324289d 100644
--- a/website/content/docs/api-gateway/upgrades.mdx
+++ b/website/content/docs/api-gateway/upgrades.mdx
@@ -5,9 +5,102 @@ description: >-
   Upgrade Consul API Gateway to use newly supported features. Learn about the requirements, procedures, and post-configuration changes involved in standard and specific version upgrades.
 ---
 
-# Upgrade API Gateway for Kubernetes
+# Upgrade Consul API gateway for Kubernetes
+
+Since Consul v1.15, the Consul API gateway is a native feature within the Consul binary and is installed during the normal Consul installation process. Since Consul v1.16, the CRDs necessary for using the Consul API gateway for Kubernetes are also included. You can install Consul v1.16 using the Consul Helm chart v1.2 and later. Refer to [Install API gateway for Kubernetes](/consul/docs/api-gateway/install) for additional information.
+
+## Introduction
+
+Because Consul API gateway releases as part of Consul, it no longer has an independent version number. Instead, the API gateway inherits the same version number as the Consul binary. Refer to the [release notes](/consul/docs/release-notes) for additional information. 
+
+To begin using the native API gateway, complete one of the following upgrade paths:
+
+### Upgrade from Consul on Kubernetes v1.1.x
+
+1. Complete the instructions for [upgrading to the native Consul API gateway](#upgrade-to-native-consul-api-gateway).
+
+### Upgrade from v0.4.x - v0.5.x
+ 
+1. Complete the [standard upgrade instructions](#standard-upgrade)
+1. Complete the instructions for [upgrading to the native Consul API gateway](#upgrade-to-native-consul-api-gateway).
+
+### Upgrade from v0.3.x
+
+1. Complete the instructions for [upgrading to v0.4.0](#upgrade-to-v0-4-0)
+1. Complete the [standard upgrade instructions](#standard-upgrade)
+1. Complete the instructions for [upgrading to the native Consul API gateway](#upgrade-to-native-consul-api-gateway).
+
+### Upgrade from v0.2.x
+
+1. Complete the instructions for [upgrading to v0.3.0](#upgrade-to-v0-2-0)
+1. Complete the instructions for [upgrading to v0.4.0](#upgrade-to-v0-4-0)
+1. Complete the [standard upgrade instructions](#standard-upgrade)
+1. Complete the instructions for [upgrading to the native Consul API gateway](#upgrade-to-native-consul-api-gateway).
+
+### Upgrade from v0.1.x
+
+1. Complete the instructions for [upgrading to v0.2.0](#upgrade-to-v0-2-0)
+1. Complete the instructions for [upgrading to v0.3.0](#upgrade-to-v0-3-0)
+1. Complete the instructions for [upgrading to v0.4.0](#upgrade-to-v0-4-0)
+1. Complete the [standard upgrade instructions](#standard-upgrade)
+1. Complete the instructions for [upgrading to the native Consul API gateway](#upgrade-to-native-consul-api-gateway).
+
+## Upgrade to native Consul API gateway
+
+You must begin the upgrade procedure with Consul API gateway v1.1 installed. If you are currently using a version of Consul API gateway older than v1.1, complete the necessary stages of the upgrade path to v1.1 before you begin upgrading to the native API gateway. Refer to the [Introduction](#introduction) for an overview of the upgrade paths.
+
+### Consul-managed CRDs
+
+If you are able to tolerate downtime for your applications, you should delete previously installed CRDs and allow Consul to install and manage them for future updates. The amount of downtime depends on how quickly you are able to install the new version of Consul. If you are unable to tolerate any downtime, refer to [Self-managed CRDs](#self-managed-crds) for instructions on how to upgrade without downtime.
+
+1. Run the `kubectl delete` command and reference the kustomize directory to delete the existing CRDs. The following example deletes the CRDs that were installed with API gateway v0.5.1: 
+
+  ```shell-session
+  $ kubectl delete --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.5.1"
+  ``` 
+
+1. Issue the following command to apply the configuration and complete the installation:
+
+  ```shell-session
+  $ kubectl apply -f apigw-installation.yaml
+  ```
+
+1. Change any existing `Gateways` to reference the new `GatewayClass` `consul`. Refer to [gatewayClass](/consul/docs/api-gateway/configuration/gateway#gatewayclassname) for additional information.
+
+1. After updating all of your `gateway` configurations to use the new controller, you can complete the upgrade again and completely remove the `apiGateway` block to remove the old controller. 
+
+### Self-managed CRDs
+
+If you are unable to tolerate any downtime, you can complete the following steps to upgrade to the native Consul API gateway. If you choose this upgrade option, you must continue to manually install the CRDs necessary for operating the API gateway. 
+
+1. Create a values file that installs the version of Consul API gateway that ships with Consul and disables externally-managed CRDs:
+
+  <CodeBlock heading="apigw-installation.yaml">
+
+  ```yaml
+  global:
+    image: hashicorp/consul:1.16
+    imageK8S: hashicorp/consul-k8s-control-plane
+  connectInject:
+    apiGateway:
+      manageExternalCRDs: false
+  apiGateway:
+    enabled: true
+    image: hashicorp/consul-api-gateway:0.5.4
+    managedGatewayClass:
+      enabled: true
+  ```
+
+  </CodeBlock>
+
+1. Issue the following command to apply the configuration and complete the installation:
+
+  ```shell-session
+  $ kubectl apply -f apigw-installation.yaml
+  ```
+
+1. Change any existing `Gateways` to reference the new `GatewayClass` `consul`. Refer to [gatewayClass](/consul/docs/api-gateway/configuration/gateway#gatewayclassname) for additional information.
 
-This topic describes how to upgrade Consul API Gateway.
 
 ## Upgrade to v0.4.0
 
@@ -34,7 +127,9 @@ Ensure that the following requirements are met prior to upgrading:
 <a name="v0.4.0-post-upgrade-configuration-changes"/>
 
 ### Post-upgrade configuration changes
+
 Complete the following steps after performing standard upgrade procedure.
+
 #### Requirements
 
 - Consul API Gateway should be running version v0.4.0.