diff --git a/website/content/docs/api-gateway/consul-api-gateway-install.mdx b/website/content/docs/api-gateway/consul-api-gateway-install.mdx index 3cfa04d5cf..43e9cb3113 100644 --- a/website/content/docs/api-gateway/consul-api-gateway-install.mdx +++ b/website/content/docs/api-gateway/consul-api-gateway-install.mdx @@ -11,16 +11,18 @@ This topic describes how to use the Consul API Gateway add-on module. It include ## Requirements -Ensure that the environment you are deploying Consul API Gateway in meets the requirements listed in the [Technical Specifications](/docs/api-gateway/tech-specs). This includes validating that the requirements for minimum versions of software are met. +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. See the [Release Notes][rel-notes] for the version of API Gateway you are deploying. ## Installation +-> **NOTE:** When you see `VERSION` in examples of commands or configuration settings, replace `VERSION` with the version number of the release you are installing, like `0.2.0`. If there is a lower case "v" in front of `VERSION` the version number needs to follow the "v" as is `v0.2.0` + 1. Issue the following command to install the CRDs: ```shell-session - $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.2.0" + $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=vVERSION" ``` @@ -38,7 +40,7 @@ Ensure that the environment you are deploying Consul API Gateway in meets the re enabled: true apiGateway: enabled: true - image: hashicorp/consul-api-gateway:0.2.0 + image: hashicorp/consul-api-gateway:VERSION ``` @@ -355,3 +357,10 @@ The `MeshService` configuration holds a reference to an externally-managed Consu | `name` | Specifies the service name for a Consul service. It is assumed this service will exist in either the `consulDestinationNamespace` or mirrored Consul namespace from where this custom resource is defined, depending on the Helm configuration. Refer to the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_meshservices.yaml) for the complete specification. + + +[tech-specs]: /docs/api-gateway/tech-specs +[rel-notes]: /docs/release-notes diff --git a/website/content/docs/api-gateway/upgrade-specific-versions.mdx b/website/content/docs/api-gateway/upgrade-specific-versions.mdx index ef10133daf..fa38c15bd8 100644 --- a/website/content/docs/api-gateway/upgrade-specific-versions.mdx +++ b/website/content/docs/api-gateway/upgrade-specific-versions.mdx @@ -21,13 +21,15 @@ Ensure that the following requirements are met prior to upgrading: - You should have the ability to run `kubectl` CLI commands. - `kubectl` should be configured to point to the cluster containing the installation you are upgrading. - You should have the following permission rights on your Kubernetes cluster: - * `HTTPRoute.read` - * `TCPRoute.read` - * `ReferencePolicy.create` + - `HTTPRoute.read` + - `TCPRoute.read` + - `ReferencePolicy.create` - (Optional) The [jq](https://stedolan.github.io/jq/download/) command line processor for JSON can be installed, which will ease route retrieval during the upgrade process. ## Procedure +-> **NOTE** When you see `VERSION` in examples of commands or configuration settings, replace `VERSION` with the version number of the release you are installing, like `0.2.0`. If there is a lower case "v" in front of `VERSION` the version number needs to follow the "v" as is `v0.2.0` + 1. Verify the current version of the `consul-api-gateway-controller` `Deployment`: ```shell-session @@ -45,6 +47,7 @@ Ensure that the following requirements are met prior to upgrading: ```shell-session $ kubectl get HTTPRoute,TCPRoute --output json --all-namespaces ``` + Note that the command only retrieves `HTTPRoutes` and `TCPRoutes`. `TLSRoutes` and `UDPRoutes` are not supported in v0.1.0. If you have any active `HTTPRoutes` or `TCPRoutes`, you will receive output similar to the following response. The output has been truncated to show only relevant fields: @@ -93,6 +96,7 @@ Ensure that the following requirements are met prior to upgrading: ... ... ``` + 1. Inspect the `backendRefs` entries for each of the routes. If a `namespace` field is not defined in the `backendRef` or if the namespace matches the namespace of the route, then no additional action is required for the `backendRef`. Otherwise, note the `group`, `kind`, `name`, and `namespace` field values for `backendRef` configurations that have a `namespace` defined that do not match the namespace of the parent route. You must also note the `kind` and `namespace` of the parent route. You will need these to create a `ReferencePolicy` that explicitly allows each cross-namespace route-to-service pair to prevent the route from breaking (see [step 5](#create-reference-policy)). @@ -120,12 +124,13 @@ Ensure that the following requirements are met prior to upgrading: name: web-backend namespace: gateway-namespace ``` + Skip to [step 8](#step-8) if your list is empty. -1. If you have installed [`jq`](https://stedolan.github.io/jq/), issue the following command to get all `HTTPRoutes` and `TCPRoutes` and filter for routes that require a `ReferencePolicy`. +1. If you have installed [`jq`](https://stedolan.github.io/jq/), issue the following command to get all `HTTPRoutes` and `TCPRoutes` and filter for routes that require a `ReferencePolicy`. ```shell-session $ kubectl get HTTPRoute,TCPRoute -o json -A | jq -r '.items[] | {name: .metadata.name, namespace: .metadata.namespace, kind: .kind, crossNamespaceBackendReferences: ( .metadata.namespace as $parentnamespace | .spec.rules[] .backendRefs[] | select(.namespace != null and .namespace != $parentnamespace ) )} ' @@ -165,6 +170,7 @@ Ensure that the following requirements are met prior to upgrading: } } ``` + If your output is empty, skip to [step 8](#step-8). @@ -197,6 +203,7 @@ Ensure that the following requirements are met prior to upgrading: kind: Service name: web-backend ``` + 1. If you have already created a `ReferencePolicy`, modify it to allow your route and save it as `referencepolicy.yaml`. Note that each `ReferencePolicy` only supports one `to` field and one `from` field (refer the [`ReferencePolicy`](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/referencepolicy/#api-design-decisions) documentation). As a result, you may need to create multiple `ReferencePolicy`s. @@ -210,10 +217,10 @@ Ensure that the following requirements are met prior to upgrading: Repeat this step as needed until each of your cross-namespace routes have a corresponding `ReferencePolicy`. -1. Issue the following command to install the v.0.2.0 CRDs into your cluster: +1. Issue the following command to install the new version of CRDs into your cluster: ``` shell-session - $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=0.2.0" + $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=vVERSION" ``` 1. Update `apiGateway.image` in `values.yaml`: @@ -223,9 +230,10 @@ Ensure that the following requirements are met prior to upgrading: ```yaml ... apiGateway: - image: hashicorp/consul-api-gateway:0.2.0 + image: hashicorp/consul-api-gateway:VERSION ... ``` + 1. Issue the following command to upgrade your Consul installation: @@ -247,6 +255,7 @@ Ensure that the following requirements are met prior to upgrading: ---> 1. (Optional) Delete and recreate your routes. Note that it may take several minutes for attached routes to reconcile and start reporting bind errors. + ```shell-session $ kubectl delete --filename $ kubectl create --filename @@ -254,4 +263,4 @@ Ensure that the following requirements are met prior to upgrading: ## Post-Upgrade Configuration Changes -No configuration changes are required for this upgrade. +No additional configuration changes are required for this upgrade. diff --git a/website/content/docs/release-notes/consul-api-gateway/v0_2_x.mdx b/website/content/docs/release-notes/consul-api-gateway/v0_2_x.mdx index 0ff7a0a7a8..cb5370b3f0 100644 --- a/website/content/docs/release-notes/consul-api-gateway/v0_2_x.mdx +++ b/website/content/docs/release-notes/consul-api-gateway/v0_2_x.mdx @@ -37,7 +37,7 @@ Supported version of the Gateway API spec: `v1alpha2`(v0.4.1) ## Upgrading -~>**Note**: If your current deployment has routes and and services that cross namespaces, those routes will not be applied to their gateways until cross namespace reference policies are created for them. +~> **Note**: If your current deployment has routes and and services that cross namespaces, those routes will not be applied to their gateways until cross namespace reference policies are created for them. For detailed information on upgrading, including how to create the required reference policies, please refer to the [upgrade details page](/docs/api-gateway/upgrade-specific-versions) @@ -48,3 +48,4 @@ The changelogs for this major release version and any maintenance versions are l -> **Note**: These links will take you to the changelogs on the GitHub website. - [0.2.0](https://github.com/hashicorp/consul-api-gateway/releases/tag/v0.2.0) +- [0.2.1](https://github.com/hashicorp/consul-api-gateway/releases/tag/v0.2.1)