# Technical Documentation: hashicorp/consul > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/hashicorp/consul) ### Overview (`README.md`)

Consul logo Consul

[](LICENSE) [](https://hub.docker.com/r/hashicorp/consul) [](https://goreportcard.com/report/github.com/hashicorp/consul) [](https://github.com/hashicorp/consul/actions/workflows/go-tests.yml) Consul is a distributed, highly available, and data center aware solution to connect and configure applications across dynamic, distributed infrastructure. * Documentation and Tutorials: [https://developer.hashicorp.com/consul] * Forum: [Discuss](https://discuss.hashicorp.com/c/consul) Consul provides several key features: * **Multi-Datacenter** - Consul is built to be datacenter aware, and can support any number of regions without complex configuration. * **Service Mesh** - Consul Service Mesh enables secure service-to-service communication with automatic TLS encryption and identity-based authorization. Applications can use sidecar proxies in a service mesh configuration to establish TLS connections for inbound and outbound connections with Transparent Proxy. * **API Gateway** - Consul API Gateway manages access to services within Consul Service Mesh, allow users to define traffic and authorization policies to services deployed within the mesh. * **Service Discovery** - Consul makes it simple for services to register themselves and to discover other services via a DNS or HTTP interface. External services such as SaaS providers can be registered as well. * **Health Checking** - Health Checking enables Consul to quickly alert operators about any issues in a cluster. The integration with service discovery prevents routing traffic to unhealthy hosts and enables service level circuit breakers. * **Dynamic App Configuration** - An HTTP API that allows users to store indexed objects within Consul, for storing configuration parameters and application metadata. Consul runs on Linux, macOS, FreeBSD, Solaris, and Windows and includes an optional [browser based UI](https://demo.consul.io). A commercial version called [Consul Enterprise](https://developer.hashicorp.com/consul/docs/enterprise) is also available. **Please note**: We take Consul's security and our users' trust very seriously. If you believe you have found a security issue in Consul, please [responsibly disclose](https://www.hashicorp.com/security#vulnerability-reporting) by contacting us at security@hashicorp.com. ## Quick Start A few quick start guides are available on the Consul website: * **Standalone binary install:** https://learn.hashicorp.com/collections/consul/get-started-vms * **Minikube install:** https://learn.hashicorp.com/tutorials/consul/kubernetes-minikube * **Kind install:** https://learn.hashicorp.com/tutorials/consul/kubernetes-kind * **Kubernetes install:** https://learn.hashicorp.com/tutorials/consul/kubernetes-deployment-guide * **Deploy HCP Consul:** https://learn.hashicorp.com/tutorials/consul/hcp-gs-deploy ## Documentation Full, comprehensive documentation is available on the Consul website: https://developer.hashicorp.com/consul/docs ## Contributing Thank you for your interest in contributing! Please refer to [CONTRIBUTING.md](https://github.com/hashicorp/consul/blob/main/.github/CONTRIBUTING.md) for guidance. For contributions specifically to the browser based UI, please refer to the UI's [README.md](https://github.com/hashicorp/consul/blob/main/ui/packages/consul-ui/README.md) for guidance. --- ### Overview (`api/README.md`) # Consul API Client This package provides the `api` package which provides programmatic access to the full Consul API. The full documentation is available on [Godoc](https://godoc.org/github.com/hashicorp/consul/api). ## Usage Below is an example of using the Consul client. To run the example, you must first [install Consul](https://developer.hashicorp.com/consul/downloads) and [Go](https://go.dev/doc/install). To run the client API, create a new Go module. ```shell go mod init consul-demo ``` Copy the example code into a file called `main.go` in the directory where the module is defined. As seen in the example, the Consul API is often imported with the alias `capi`. ```go package main import ( "fmt" capi "github.com/hashicorp/consul/api" ) func main() { // Get a new client client, err := capi.NewClient(capi.DefaultConfig()) if err != nil { panic(err) } // Get a handle to the KV API kv := client.KV() // PUT a new KV pair p := &capi.KVPair{Key: "REDIS_MAXCLIENTS", Value: []byte("1000")} _, err = kv.Put(p, nil) if err != nil { panic(err) } // Lookup the pair pair, _, err := kv.Get("REDIS_MAXCLIENTS", nil) if err != nil { panic(err) } fmt.Printf("KV: %v %s\n", pair.Key, pair.Value) } ``` Install the Consul API dependency with `go mod tidy`. In a separate terminal window, start a local Consul server. ```shell consul agent -dev -node machine ``` Run the example. ```shell go run . ``` You should get the following result printed to the terminal. ```shell KV: REDIS_MAXCLIENTS 1000 ``` After running the code, you can also view the values in the Consul UI on your local machine at http://localhost:8500/ui/dc1/kv --- ### Overview (`bench/README.md`) Consul Benchmark ================ This repo contains the automation necessary for the Consul benchmarks. There is a single main Packer file `bench.json`. To use it, the variables for `do_client_id` and `do_api_key` must be provided. These correspond to your DigitalOcean client ID and API key. When Packer runs, it will generate 3 images: * bench-bootstrap - Consul server in bootstrap mode * bench-server - Consul server * bench-worker - Worker node For the benchmark you should start 1 bootstrap instance, and 2 normal servers. As many workers as desired can be started. Once the nodes are up, you must SSH into one of the Consul servers. Connect all the nodes with: $ consul join ... This will connect all the nodes within the same datacenter. To run the benchmarks, use the Makefile: $ cd / $ make # Runs all the benchmarks $ make put # Runs only the PUT benchmarks There is no good way to currently cause multiple workers to run at the same time, so I just type in the make command and rapidly start the test on all workers. It is not perfect, but the test runs long enough that the calls overlap. --- ### Overview (`sdk/README.md`) ## Internal SDK Please note that this folder, while public, is not meant for new consumers of these libraries; this should currently be considered an internal, not external, SDK. It is public due to existing needs from other HashiCorp software. The tags in this folder will stay at the 0.x.y level; accordingly users should expect that things can move around, disappear, or change API at any time. --- ### Overview (`test-integ/README.md`) # test-integ Go integration tests for consul. `/test/integration` also holds integration tests; they need migrating. These should use the [testing/deployer framework](../testing/deployer) to bring up some local testing infrastructure and fixtures to run test assertions against. Where reasonably possible, try to bring up infrastructure interesting enough to be able to run many related sorts of tests against it, rather than waiting for many similar clusters to be provisioned and torn down. This will help ensure that the integration tests do not consume CPU cycles needlessly. ## Prerequisites Before you can run these tests, a fresh dev build should be created and tagged for automatic use by tests using `utils.TargetImages()`. This can be done by the toplevel consul make target: make test-deployer-setup You can run the entire set of deployer integration tests using: make test-deployer # everything except peering_commontopo make test-deployer-peering # just peering_commontopo You can also run them one by one if you like: go test ./connect/ -run Test_Snapshot_Restore_Agentless -v You can have the logs stream unbuffered directly to your terminal which can help diagnose stuck tests that would otherwise need to fully timeout before the logs would print by also setting the `NOLOGBUFFER=1` environment variable. ## Getting started Deployer tests have three main parts: 1. Declarative topology description. 2. Launching the infrastructure defined by that description. 3. Making test assertions about the infrastructure. Some tests may also have an optional _mutation_ phase followed by additional assertions. These are only needed if the test needs to observe a reaction in the system to a change in the environment or configuration. ### Topology description Test authors craft a declarative description of the infrastructure necessary to exist for the test. These are also referred to as a "topology". These are comprised of 4 main parts: - **Images**: The set of docker images and specific versions that will be used by default if not overridden on each Cluster or Node. - Consul CE - Consul Enterprise - Consul Dataplane - Envoy Proxy - **Networks**: The non-overlapping networks that should exist for use by the Clusters. - **Clusters**: The unique Consul clusters that should exist. - **Nodes**: A "box with ip address(es)". This should feel a bit like a VM or a Kubernetes Pod as an enclosing entity. - **Workloads**: The list of service instances that will execute on the given node. - **InitialConfigEntries**: Config entries that should be created as part of the fixture and that make sense to include as part of the test definition, rather than something created during the test assertion phase. - **InitialResources**: Resources that should be created as part of the fixture and that make sense to include as part of the test definition, rather than something created during the test assertion phase. - **Peerings**: The peering relationships between Clusters to establish. In the [topoutil](./topoutil) package there are some helpers for defining common sets of nodes or workloads like Consul Servers, Mesh Gateways, or [fortio servers](https://github.com/fortio/fortio) #### Useful topology concepts Consul has a lot of independent configurables that can greatly increase the testing configuration space required to flush out any bugs. The topology definition was designed to be easily "exploded" to create testing microcosms on a variety of axes: - agentful (clients) vs agentless (dataplane) - tenancies (partitions, namespaces) - locally or across a peering Since the topology is just a declarative struct, a test author could rewrite any one of these attributes with a single field (such as `Node.Kind`) and cause the identical test to run against the other configuration. With the addition of a few `if enterprise {}` blocks and `for` loops, a test author could easily write one test of a behavior and execute it to cover agentless, agentful, and non-default tenancy in a few extra lines of code. #### Non-optional security settings The test framework always enables ACLs in default deny mode and provisions minimal-permission tokens automatically to the various containers that need them. TLS certificates are similarly minted and distributed to all components that need them. ### Launching a topology There is a [sprawltest](../testing/deployer/sprawl/sprawltest) package that has utilities to bring up a topology in the context of a Go test. This is basically a one-liner: sp := sprawltest.Launch(t, config) After this line returns you will have a handle (`sp`) to the running cluster and can use it to get ready-made api clients, http clients, gRPC resource client, or test sockets open to a variety of the topology components for use in authoring test code. This helper will rig up a `t.Cleanup` handler that will destroy all resources created during the test. This can be opted-out of by setting the `SPRAWL_KEEP_RUNNING=1` environment variable before running the tests. ### Upgrade test We are migrating upgrade tests from consul-container(`/test/integration`) to this directory using the [testing/deployer framework](../testing/deployer). The current implementation supports two upgrade strategies: [standard upgrade](https://developer.hashicorp.com/consul/docs/upgrading/instructions/general-process) and [autopilot upgrade](https://developer.hashicorp.com/consul/tutorials/datacenter-operations/upgrade-automation). The basic test scenario can be found in `./test-integ/upgrade/basic`. ### Test assertions Typical service mesh tests want to ensure that use of a service from another service behaves in a certain way. Because the entire set of components is known declaratively, we can process it into a flat list of known source/destination relationships: ships := topology.ComputeRelationships() This works hand-in-hand with the topology concepts mentioned above to programmatically verify independent subunits of a topology that may exist (this is helpful for things like testing multiple tenancy configurations without duplicating all of the assertion code). This can also be pretty printed to the log for diagnostic purposes with: t.Log(topology.RenderRelationships(ships)) Which looks like this: $ NOLOGBUFFER=1 go test ./catalogv2/ -run TestBasicL4ExplicitDestinations -v ...(skipping a bunch of output)... 2023-11-08T11:48:04.395-0600 [INFO] TestBasicL4ExplicitDestinations: topology is ready for use: elapsed=33.510298357s explicit_destinations_test.go:55: DOWN |node |service |port |UP |service | dc1 |default/dc1-box2 |default/default/single-client |5000 |dc1 |default/default/single-server | dc1 |default/dc1-box4 |default/default/multi-client |5000 |dc1 |default/default/multi-server | dc1 |default/dc1-box4 |default/default/multi-client |5001 |dc1 |default/default/multi-server | | | | | | | === RUN TestBasicL4ExplicitDestinations/relationship:_default/default/single-client_on_default/dc1-box2_in_dc1_via_:5000_=>_default/default/single-server_in_dc1_port_http service.go:224: making call to http://10.238.170.5:5000 service.go:245: ...got response code 200 === RUN TestBasicL4ExplicitDestinations/relationship:_default/default/multi-client_on_default/dc1-box4_in_dc1_via_:5000_=>_default/default/multi-server_in_dc1_port_http service.go:224: making call to http://10.238.170.7:5000 service.go:245: ...got response code 200 === RUN TestBasicL4ExplicitDestinations/relationship:_default/default/multi-client_on_default/dc1-box4_in_dc1_via_:5001_=>_default/default/multi-server_in_dc1_port_http-alt service.go:224: making call to http://10.238.170.7:5001 service.go:245: ...got response code 200 2023-11-08T11:48:04.420-0600 [INFO] TestBasicL4ExplicitDestinations.tfgen: Running 'terraform destroy'... --- PASS: TestBasicL4ExplicitDestinations (40.60s) --- PASS: TestBasicL4ExplicitDestinations/relationship:_default/default/single-client_on_default/dc1-box2_in_dc1_via_:5000_=>_default/default/single-server_in_dc1_port_http (0.01s) --- PASS: TestBasicL4ExplicitDestinations/relationship:_default/default/multi-client_on_default/dc1-box4_in_dc1_via_:5000_=>_default/default/multi-server_in_dc1_port_http (0.01s) --- PASS: TestBasicL4ExplicitDestinations/relationship:_default/default/multi-client_on_default/dc1-box4_in_dc1_via_:5001_=>_default/default/multi-server_in_dc1_port_http-alt (0.01s) PASS ok github.com/hashicorp/consul/test-integ/catalogv2 40.612s There is a ready-made helper to assist with making common inquiries to Consul and Envoy that you can create in your test: asserter := topoutil.NewAsserter(sp) asserter.UpstreamEndpointStatus(t, svc, clusterPrefix+".", "HEALTHY", 1) --- ### Overview (`types/README.md`) # Consul `types` Package The Go language has a strong type system built into the language. The `types` package corrals named types into a single package that is terminal in `go`'s import graph. The `types` package should not have any downstream dependencies. Each subsystem that defines its own set of types exists in its own file, but all types are defined in the same package. # Why > Everything should be made as simple as possible, but not simpler. `string` is a useful container and underlying type for identifiers, however the `string` type is effectively opaque to the compiler in terms of how a given string is intended to be used. For instance, there is nothing preventing the following from happening: ```go // `map` of Widgets, looked up by ID var widgetLookup map[string]*Widget // ... var widgetID string = "widgetID" w, found := widgetLookup[widgetID] // Bad! var widgetName string = "name of widget" w, found := widgetLookup[widgetName] ``` but this class of problem is entirely preventable: ```go type WidgetID string var widgetLookup map[WidgetID]*Widget var widgetName ``` TL;DR: intentions and idioms aren't statically checked by compilers. The `types` package uses Go's strong type system to prevent this class of bug. --- ### Overview (`ui/README.md`) # Consul UI Monorepo This monorepo contains multiple projects, the UI for Consul and addons and packages used by the UI. This top-level repository provides limited common tasks, such as installation and commit assistance. However, most tasks must be executed from within a subproject, e.g. running or testing. **If you are looking to work on the Consul UI you probably want to read the README that is in `./packages/consul-ui/README.md`.** **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - [Prerequisites](#prerequisites) - [Installation](#installation) - [Pnpm Commands](#pnpm-commands) - [Contributing](#contributing) - [Building ToC](#building-toc) ## Prerequisites You will need the following things properly installed on your computer. * [Git][git] * [Node.js][node] * [Pnpm][pnpm] installed globally * [Google Chrome][chrome] * [Firefox][firefox] [git]: https://git-scm.com/ [node]: https://nodejs.org/ [pnpm]: https://pnpm.io/ [chrome]: https://google.com/chrome/ [firefox]: https://firefox.com/ ## Installation * `git clone https://github.com/hashicorp/consul.git` this repository * `cd ui` * `pnpm i` ## Pnpm Commands List of available project commands. `pnpm run ` | Command | Description | |---------------------|------------------------------------| | doc:toc | Re-builds the ToC for this README. | | compliance:licenses | Checks that all dependencies have CE-compatible licenses. | For Vercel preview deployments, the workspace-level configuration lives in `./vercel.json`. ## Contributing ### Building ToC To autogenerate a ToC (table of contents) for this README, run `pnpm doc:toc`. Please update the ToC whenever editing the structure of README. --- ### Overview (`agent/uiserver/README.md`) # uiserver The contents of `dist/` are generated by `make ui` in the root of this repo which compiles `ui` assets and copies them here. A CI job (`publish-static-assets`) will detect any diffs in `ui` files and commit the compiled files. Avoid committing files manually to `dist/`. --- ### Overview (`internal/go-sso/README.md`) # go-sso This is a Go library that is being incubated in Consul to assist in doing opinionated OIDC-based single sign on. The `go.mod.sample` and `go.sum.sample` files are what the overall real `go.mod` and `go.sum` files should end up being when extracted from the Consul codebase. --- ### Overview (`sdk/testutil/README.md`) Consul Testing Utilities ======================== This package provides some generic helpers to facilitate testing in Consul. TestServer ========== TestServer is a harness for managing Consul agents and initializing them with test data. Using it, you can form test clusters, create services, add health checks, manipulate the K/V store, etc. This test harness is completely decoupled from Consul's core and API client, meaning it can be easily imported and used in external unit tests for various applications. It works by invoking the Consul CLI, which means it is a requirement to have Consul installed in the `$PATH`. Following is an example usage: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ### Overview (`test-integ/peering_commontopo/README.md`) # CONSUL PEERING COMMON TOPOLOGY TESTS These peering tests all use a `commonTopo` (read: "common topology") to enable sharing a deployment of a Consul. Sharing a deployment of Consul cuts down on setup time. To run these tests, you will need to have docker installed. Next, make sure that you have all the required consul containers built: ``` make test-deployer-setup ``` ## Non-Shared CommonTopo Tests The tests in question are designed in a manner that modifies the topology. As a result, it is not possible to share the testing environment across these tests. ## Shared CommonTopo Tests The tests in question are designed in a manner that does not modify the topology in any way that would interfere with other tests. As a result, it is possible to share the testing environment across these tests. To run all consul peering tests with no shared topology, run the following command: ``` cd /path/to/peering_commontopo go test -timeout=10m -v -no-share-topo . ``` To run all peering tests with shared topology only: ``` cd /path/to/peering_commontopo go test -timeout=10m -run '^TestSuitesOnSharedTopo' -v . ``` To run individual peering topology tests: ``` cd /path/to/peering_commontopo go test -timeout=10m -run '^TestSuiteExample' -v -no-share-topo . ``` ## Local Development and Testing If writing tests for peering with no shared topology, this recommendation does not apply. The following methods below not necessarily need to be implmented. For shared topology tests, all the methods in the `sharedTopoSuite` interface must be implemented. - `testName()` prepends the test suite name to each test in the test suite. - `setup()` phase must ensure that any resources added to the topology cannot interfere with other tests. Principally by prefixing. - `test()` phase must be "passive" and not mutate the topology in any way that would interfere with other tests. Common topology peering tests are defined in the [test-integ/peering_commontopo/](/test-integ/peering_commontopo/) directory and new peering integration tests should always be added to this location. Adding integration tests that does not modify the topology should always start by invoking ```go runShareableSuites(t, testSuiteExample) ``` else ```go func TestSuiteExample(t *testing.T) { ct := NewCommonTopo(t) s := &testSuiteExample{} s.setup(t, ct) ct.Launch(t) s.test(t, ct) } ``` Some of these tests *do* mutate in their `test()` phase, and while they use `commonTopo` for the purpose of code sharing, they are not included in the "shared topo" tests in `sharedtopology_test.go`. --- ### Overview (`test/load/README.md`) # Terraform Consul Load Testing Consul Load Testing is used to capture baseline performance metrics for Consul under stress. This will assist in ensuring there are no performance regressions during releases and substantial changes to Consul. Per the defaults, the test runs for 10 minutes with 25 virtual users spawned by k6. Instance sizes for test instances are `t2.small` and for the Consul cluster `m5n.large`. All metrics from Consul are pushed to a datadog dashboard for user review. This relies on the [Gruntwork's Terraform AWS Consul Module](https://github.com/hashicorp/terraform-aws-consul) which *by default* creates 3 Consul servers across 3 availability zones. A load test instance which has an image that is configured with the necessary scripts and [k6](https://k6.io/) is created and sends traffic to a load balancer. The load balancer will distribute requests across the Consul clients who will ultimately forward the requests to the servers. ## How to use [Terraform](https://www.terraform.io/downloads.html) and [Packer](https://www.packer.io/downloads), AWS and [Datadog](https://docs.datadoghq.com/getting_started/) are required to use this. All of this, except the AWS resources that will be utilized, are free. This repo has the following folder structure: * packer: This contains all the necessary stuff to make the load test and the Consul AMI to be utilized in Terraform. * terraform: This contains all the relevant Terraform files ## Getting Started 1) Download all necessary tools listed (Terraform, Packer) 2) Set up an [AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) and a [Datadog account](https://docs.datadoghq.com/getting_started/) - downloading the Datadog client is not necessary. 3) Configure your AWS credentials using one of the [options supported by the AWS SDK](http://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html). Usually, the easiest option is to set the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_DEFAULT_REGION` environment variables. 4) Follow the [Packer README](./packer/README.md) to generate your load test and Consul AMIs 5) Follow the [Terraform README](./terraform/README.md) to stand up the infrastructure in AWS 6) Watch the results in either your datadog dashboard or in the output of your Terraform Apply ## Debugging in Datadog Consul has hundreds of metrics to choose from. We recommend reading over [Datadog's article](https://www.datadoghq.com/blog/consul-metrics/#communication-metrics) that breaks down relevant Consul metrics, especially on their "communication" portion. This test runs solely based on making requests to endpoints which is what makes that section so relevant. --- ### Overview (`testing/deployer/README.md`) [](https://pkg.go.dev/github.com/hashicorp/consul/testing/deployer) ## Summary This is a Go library used to launch one or more Consul clusters that can be peered using the cluster peering feature. Under the covers `terraform` is used in conjunction with the [`kreuzwerker/docker`](https://registry.terraform.io/providers/kreuzwerker/docker/latest) provider to manage a fleet of local docker containers and networks. ### Configuration The complete topology of Consul clusters is defined using a topology.Config which allows you to define a set of networks and reference those networks when assigning nodes and workloads to clusters. Both Consul clients and `consul-dataplane` instances are supported. Here is an example configuration with two peered clusters: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` Once you have a topology configuration, you simply call the appropriate `Launch` function to validate and boot the cluster. You may also modify your original configuration (in some allowed ways) and call `Relaunch` on an existing topology which will differentially adjust the running infrastructure. This can be useful to do things like upgrade instances in place or subly reconfigure them. ### For Testing It is meant to be consumed primarily by unit tests desiring a complex reasonably realistic Consul setup. For that use case use the `sprawl/sprawltest` wrapper: ``` func TestSomething(t *testing.T) { cfg := &topology.Config{...} sp := sprawltest.Launch(t, cfg) // do stuff with 'sp' } ``` --- ### Overview (`test/load/packer/README.md`) # Terraform Consul Load Testing Packer will output AMI IDs when it completes - save these AMI IDs as Terraform will require them later. The generated ami will have common tag `Environment = "consul-load-test"`. ``` ==> Builds finished. The artifacts of successful builds are: --> amazon-ebs: AMIs were created: us-east-1: ami-19601070 ``` ## Consul AMI: Within the `consul-ami/` directory 1) Retrieve your [Datadog API key]((https://docs.datadoghq.com/account_management/api-app-keys/#api-keys)), set this as an environment variable, ex: `export DD_API_KEY=$YOURDDAPIKEYHERE` 2) Set the AWS_DEFAULT_REGION for Packer, ex: `export AWS_DEFAULT_REGION=us-east-1` 3) Set up AWS credentials, ex: `export AWS_ACCESS_KEY_ID=#YOURAWSKEYID & export AWS_SECRET_ACCESS_KEY=YOURAWSKEY` 4) Run `packer build consul.pkr.hcl`. For additional customization you can add [tags](https://docs.datadoghq.com/getting_started/tagging/assigning_tags/?tab=noncontainerizedenvironments) within the `scripts/datadog.yaml` file. An example of a tag could be `"consul_version" : "consulent_175"`. These tags are searchable through the datadog dashboard. Another form of customization is changing the datacenter tag within `scripts/telemetry.json`, however it is defaulted to `us-east-1`. ## Load Test AMI Within the `loadtest-ami/` directory 1) Set the AWS_DEFAULT_REGION for Packer, ex: `export AWS_DEFAULT_REGION=us-east-1` 2) Run the command `packer build loadtest.pkr.hcl` The script that k6 runs is found within `scripts/loadtest.js`. This script can be updated to send requests to more Consul endpoints. For additional information on k6 please check out their [guides](https://k6.io/docs/getting-started/running-k6). --- ### Overview (`test/load/terraform/README.md`) # Terraform Consul Load Testing ## How to use 1. Build an image with the desired Consul version and a load test image in the Packer folder [here](../packer). 2. Create your own `vars.tfvars` file in this directory. 3. Place the appropriate AMI IDs in the `consul_ami_id` and `test_server_ami` variables. If no AMI ID is specified it will default to pulling from latest. 4. Set either `consul_version` or `consul_download_url`. If neither is set it will default to utilizing Consul 1.9.0 5. AWS Variables are set off of environment variables. Make sure to export necessary variables [shown here](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#environment-variables). 6. Run `terraform init` once to setup the working directory. 7. Run `terraform plan -var-file=vars.tfvars`, and then `terraform apply -var-file=vars.tfvars` when ready. 8. Upon completion k6 should run and push metrics to the desired Datadog dashboard. An example of a `vars.tfvars` : ``` vpc_name = "consul-test-vpc" vpc_cidr = "11.0.0.0/16" vpc_allwed_ssh_cidr = "0.0.0.0/0" public_subnet_cidrs = ["11.0.1.0/24", "11.0.3.0/24"] private_subnet_cidrs = ["11.0.2.0/24"] vpc_az = ["us-east-2a", "us-east-2b"] test_instance_type = "t2.micro" test_server_ami = "ami-0ad7711e837ebe166" cluster_name = "ctest" test_public_ip = "true" instance_type = "t2.micro" ami_owners = ["******"] consul_ami_id = "ami-016d80ff5472346f0" ```` Note that `vpc_allwed_ssh_cidr` must be set to allowed the test server to be accessible from the machine running the load test, e.g., "0.0.0.0/0" (It is disabled by default). ## Customization All customization for infrastructure that is available can be found by looking through the `variables.tf` file. ## How to SSH After `terraform apply` is run Terraform should create a `keys/` directory which will give access to all instances created. For example, `ssh -i "keys/[cluster-name]-spicy-banana.pem" ubuntu@[IPADDRESS]` --- ### Overview (`ui/packages/consul-ui/README.md`) # consul-ui - [Prerequisites](#prerequisites) - [Installation](#installation) - [Pnpm Commands](#pnpm-commands) - [Running / Development](#running--development) - [Environment Variables](#environment-variables) - [Contributing/Engineering Documentation](#contributingengineering-documentation) - [Browser 'Debug Utility' Functions and 'Environment' Variables](#browser-debug-utility-functions-and-environment-variables) - [Code Generators](#code-generators) - [Running Tests](#running-tests) - [Linting](#linting) - [Building](#building) - [Running Tests in Parallel](#running-tests-in-parallel) ## Prerequisites You will need the following things properly installed on your computer. * [Git](https://git-scm.com/) * [Node.js](https://nodejs.org/) (with npm) * [pnpm](https://pnpm.io/) * [Ember CLI](https://ember-cli.com/) * [Google Chrome](https://google.com/chrome/) ## Installation * `git clone https://github.com/hashicorp/consul.git` this repository * `cd ui/packages/consul-ui` then: **To run the UI** From within `ui/packages/consul-ui` directory run: * `make start` **To run tests** From within `ui/packages/consul-ui` directory run: * `make test-oss-view` which will run the tests in Chrome (see below and/or the [testing section of the engineering docs](./docs/testing.mdx) for further detail) ## Pnpm Commands Most used tooling scripts below primarily use `make` which will `pnpm install` and in turn call node package scripts. List of available project commands. `pnpm run ` | Command | Description | | ------- | ----------- | | build:staging | Builds the UI in staging mode (ready for PR preview site). | | build:ci | Builds the UI for CI. | | build | Builds the UI for production. | | lint | Runs all lint commands. | | lint:hbs | Lints `hbs` template files. | | lint:js | Lints `js` files. | | format | Runs all auto-formatters. | | format:js | Auto-formats `js` files using Prettier. | | format:sass | Auto-formats `scss` files using Prettier. | | start | Runs the development app on a local server using the mock API. | | start:consul | Runs the development app local server using a real consul instance as the backend. | | start:staging | Runs the staging app local server. | | test | Runs the ember tests in a headless browser. | | test:view | Runs the ember tests in a non-headless browser. | | test:oss | Runs only the OSS ember tests in a headless browser. | | test:oss:view | Runs only the OSS ember tests in a non-headless browser. | | test:coverage:view | Runs only the test specified for coverage in a non-headless browser. | | test:node | Runs tests that can't be run in ember using node. | | doc:toc | Automatically generates a table of contents for this README file. | ## Running / Development The source code comes with a small development mode that runs enough of the consul API as a set of mocks/fixtures to be able to run the UI without having to run consul. * `make start` or `pnpm start` to start the ember app * Visit your app at [http://localhost:4200](http://localhost:4200). You can also run the UI against a normal Consul installation. * `consul agent -dev` to start consul listening on http://localhost:8500 * `make start-consul` to start the ember app proxying to `consul` (this will respect the `CONSUL_HTTP_ADDR` environment variable to locate the Consul installation. * Visit your app at [http://localhost:4200](http://localhost:4200). Example: ```bash CONSUL_HTTP_ADDR=http://10.0.0.1:8500 make start-consul ``` ### Environment Variables See [./docs/index.mdx](./docs/index.mdx#environment-variables) ### Branching We follow a `ui/**/**` branch naming pattern. This branch naming pattern allows front-end focused builds, such as FE tests, to run automatically in Pull Requests. Please note this only works if you are a member of the HashiCorp GitHub Org. If you are an external contributor, these tests won't run and will instead be run by a member of our team during review. Examples: - `ui/feature/add...` - `ui/bugfix/fix...` - `ui/enhancement/update...` ### Contributing/Engineering Documentation We have an in-app (only during development) component storybook and documentation site which can be visited using the [Eng Docs](http://localhost:4200/ui/docs) link in the top navigation of the UI. Alternatively all of these docs are also readable via GitHub's UI, so folks can use whatever works best for them. ### Browser 'Debug Utility' Functions and 'Environment' Variables Run `make start` then visit http://localhost:4200/ui/docs/bookmarklets for a list of debug/engineering utilities you can use to help development of the UI under certain scenarios. ### Code Generators Many classes used in the UI can be generated with ember generators, try `ember help generate` for more details ### Running Tests Tests use the mock api (see ./mock-api for details), the mock-api runs automatically during testing, you don't need to run anything separately from the below commands in order for the tests to use the mock-api. * `make test` or `pnpm run test` * `make test-view` or `pnpm run test:view` to view the tests running in Chrome For more guidance on running tests, see the [testing section of the engineering docs](./docs/testing.mdx). OSS only tests can also be run using: * `make test-oss` or `pnpm run test:oss` * `make test-oss-view` or `pnpm run test:oss:view` to view the tests running in Chrome ### Linting `make lint` currently runs linting on the majority of js files and hbs files (using `ember-template-lint`). See `.eslintrc.js` and `.eslintignore` for specific configuration. ### Building * `make build` builds the UI for production usage (env=production) * `make build-ci` builds the UI for CI/test usage (env=test) Static files are built into ./dist #### Running Tests in Parallel You probably don't need to understand this if you are simply running some tests locally. Alternatively, `ember-exam` can be used to split the tests across multiple browser instances for faster results. Most options are the same as `ember test`. To see a full list of options, run `ember exam --help`. **Note:** The `EMBER_EXAM_PARALLEL` environment variable must be set to override the default `parallel` value of `1` browser instance in [testem.js](./testem.js). To quickly run the tests across 4 parallel browser instances: ```sh make test-parallel ``` To run manually: ```sh $ EMBER_EXAM_PARALLEL=true ./node_modules/.bin/ember exam --split --parallel ``` More ways to split tests can be found in the [ember-exam README.md](https://github.com/trentmwillis/ember-exam/blob/master/README.md). ### Vercel Deploys A Vercel preview deploy Github action triggers after each pushed change in a pull request. Vercel checks if there was changes within the UI folder in the last commit. If there are no changes the build is cancelled. If the build proceeds it will include a link to the preview deploy in your PRs feed. If you were to push changes to the UI folder and then immediately follow it up with a change to something outside of the UI folder, the lastest Vercel build will be ignored. Because of this, the preview link will not get posted to the PR feed even if the original Vercel build completes. If that is the case, you may browse the Vercel deploys for the original build. Another scenario to watch for is when you rebase a series of commits, but the last commit is outside of the UI folder. Doing this will not trigger a new Vercel deploy as the last commit doesn't have any changes in the UI folder. --- ### Overview (`test/integration/connect/envoy/README.md`) # Envoy Integration Tests ## Overview These tests validate that Consul is configuring Envoy correctly. They set up various scenarios using Docker containers and then run [Bats](https://github.com/sstephenson/bats) (a Bash test framework) tests to validate the expected results. ## Running Tests To run the tests locally, `cd` into the root of the repo and run: ```console make test-envoy-integ ``` To run a specific test, run: ```console make test-envoy-integ GO_TEST_FLAGS="-run TestEnvoy/case-basic" ``` Where `case-basic` can be replaced by any directory name from this directory. ## How Do These Tests Work 1. The tests are all run through Go test via the `main_test.go` file. Each directory prefixed by `case-` is a subtest, for example, `TestEnvoy/case-basic` and `TestEnvoy/case-wanfed-gw`. 2. The real framework for this test suite lives in `run-tests.sh`. Under the hood, `main_test.go` just runs `run-tests.sh` with various arguments. 3. The tests use your local code by building a Docker image from your local directory just before executing. _Note:_ this is implemented as the `docker-envoy-integ` Makefile target which is a prerequisite to the `test-envoy-integ` target, so if you are running the tests by invoking `run-tests.sh` or `go test` manually, be sure to rebuild the Docker image to ensure you are running your latest code. 4. The tests run Docker containers connected by a shared Docker network. All tests have at least one Consul server running and then depending on the test case they will spin up additional services or gateways. Some tests run multiple Consul servers to test multi-DC setups. See the [`case-wanfed-gateway` test](./case-wanfed-gw) for an example of this. 5. At a high level, tests are set up by executing the `setup.sh` script in each directory. This script uses helper functions defined in `helpers.bash`. Once the test case is set up, the validations in `verify.bats` are run. 6. If there exists a `vars.sh` file in the top-level of the case directory, the test runner will source it prior to invoking the `run_tests`, `test_teardown` and `capture_logs` phases of the test scenario. 7. If there exists a `capture.sh` file in the top-level of the case directory, it will be executed after the test is done, but prior to the containers being removed. This is useful for capturing logs or Envoy snapshots for debugging test failures. 8. Any files matching the `*.hcl` glob will be copied to the container `$WORKDIR/$CLUSTER/consul` directory prior to running the tests. This is useful for defining Consul configuration for each agent process to load on start up. 9. In CI, the tests are executed against different Envoy versions and with both `XDS_TARGET=client` and `XDS_TARGET=server`. If set to `client`, a Consul server and client are run, and services are registered against the client. If set to `server`, only a Consul server is run, and services are registered against the server. By default, `XDS_TARGET` is set to `server`. See [this comment](https://github.com/hashicorp/consul/blob/70bb6a2abdbc5ed4a6e728e8da243c5394a631d1/test/integration/connect/envoy/run-tests.sh#L178-L212) for more information. ## Investigating Test Failures * When tests fail in CI, logs and additional debugging data are available in the artifacts of the test run. * You can re-run the tests locally by running `make test-envoy-integ GO_TEST_FLAGS="-run TestEnvoy/"` where `` is replaced with the name of the directory, e.g. `case-basic`. * You can override the envoy version by specifying `ENVOY_VERSION=` eg. `ENVOY_VERSION=1.27.0 make test-envoy-integ`. * Locally, all the logs of the failed test will be available in `workdir` in this directory. * You can run with `DEBUG=1` to print out all the commands being run, e.g. `DEBUG=1 make test-envoy-integ GO_TEST_FLAGS="-run TestEnvoy/case-basic"`. * If you want to prevent the Docker containers from being spun down after test failure, add a `sleep 9999` to the `verify.bats` test case that's failing. ## Creating a New Test Below is a rough outline for creating a new test. For the example, assume our test case will be called `my-feature`. 1. Create a new directory named `case-my-feature` 2. If the test involves multiple datacenters/clusters, create a separate subdirectory for each cluster (eg. `case-my-feature/{dc1,dc2}`) 3. Add any necessary configuration to `*.hcl` files in the respective cluster subdirectory (or the test case directory when using a single cluster). 4. Create a `setup.sh` file in the case directory 5. Create a `capture.sh` file in the case directory 6. Create a `verify.bats` file in the case directory 7. Populate the `setup.sh`, `capture.sh` and `verify.bats` files with the appropriate code for running your test, validating its state and capturing any logs or snapshots. --- ### Overview (`ui/packages/consul-ui/mock-api/README.md`) # consul-api-double Super simple API 'double' for easily visualizing the Consul API via the filesystem. This can be served via either a simple javascript HTTP server, or entirely via frontend methods if your project/circumstances means you are unable to use or it's complicated to use a backend server for testing. See [@hashicorp/api-double](https://github.com/hashicorp/api-double/) for more details. --- ### Overview (`test/integration/consul-container/test/upgrade/README.md`) # Upgrade Integration Tests - [Introduction](#introduction) - [How it works](#how-it-works) - [Getting Started](#getting-started) - [Prerequisites](#prerequisites) - [Running Upgrade integration tests](#running-upgrade-integration-tests) - [Adding a new upgrade integration test](#adding-a-new-upgrade-integration-test) - [Errors Test Cases](#errors-test-cases) - [FAQS](#faqs) ## Introduction The goal of upgrade tests is to ensure problem-free upgrades on supported upgrade paths. At any given time, Consul supports the latest minor release, and two older minor releases, e.g. 1.15, 1.14, and 1.13. Upgrades to any higher version are permitted, including skipping a minor version e.g. from 1.13 to 1.15. The upgrade tests also aim to highlight errors that may occur as users attempt to upgrade their current version to a newer version. ### How it works This diagram illustrates the deployment architecture of an upgrade test, where two consul agents (one server and one client), a static-server, static-client, and envoy sidecars are deployed. isolated > Note that all consul agents and user workloads such as application services, mesh-gateway are running in docker containers. In general, each upgrade test has the following steps: 1. Create a cluster with a specified number of server and client agents, then enable the feature to be tested. 2. Create some workload in the cluster, e.g., registering 2 services: static-server, static-client. Static-server is a simple http application and the upstream service of static-client. 3. Make additional configuration to the cluster. For example, configure Consul intention to deny connection between static client and server. Ensure that a connection cannot be made. 4. Upgrade Consul cluster to the `target-version` and restart the Envoy sidecars (we restart Envoy sidecar to ensure the upgraded Consul binary can read the state from the previous version and generate the correct Envoy configurations) 5. Re-validate the client, server and sidecars to ensure the persisted data from the previous version can be accessed in the target version. Verify connection / disconnection (e.g., deny Action) ## Getting Started ### Prerequisites To run the upgrade test, the following tools are required: - install [Go](https://go.dev/) (the version should match that of our CI config's Go image). - install [`golangci-lint`](https://golangci-lint.run/usage/install/) - install [`Makefile`](https://www.gnu.org/software/make/manual/make.html) - [`Docker`](https://docs.docker.com/get-docker/) required to run tests locally ### Running Upgrade integration tests - run `make dev-docker` - build a consul-envoy container image ```shell cd test/integration/consul-container docker build -t consul-envoy:latest-version \ --build-arg CONSUL_IMAGE=docker.mirror.hashicorp.services/consul:1.20.0-rc1 \ --build-arg ENVOY_VERSION=1.31.2 -f ./assets/Dockerfile-consul-envoy ./assets ``` - run the single test `go test -v -timeout 30m -run ^TestACL_Upgrade_Node_Token$ ./.../upgrade/` - run all upgrade tests `go test -v -timeout 30m -run ./.../upgrade` To specify targets and latest image pass `--target-version` and `--latest-version` to the tests. By default, it uses the `consul` docker image with respectively `local` and `latest` tags. To use dev consul image, pass `target-image` and `target-version`: -target-image hashicorppreview/consul -target-version 1.15-dev By default, all container's logs are written to either `stdout`, or `stderr`; this makes it hard to debug, when the test case creates many containers. To disable following container logs, run the test with `-follow-log false`. Below are the supported CLI options | Flags | Default value | Description | | ----------- | ----------- | ----------- | | --latest-image | `consul` in CE, `hashicorp/consulenterprise` in ENT | Name of the Docker image to deploy initially. | --latest-version | latest | Tag of the Docker image to deploy initially. | --target-image | `consul` in Ce, `hashicorp/consulenterprise` in ENT | Name of the Docker image to upgrade to. | --target-version | local | Tag of the Docker image to upgrade to. `local` is the tag built by `make dev-docker` above. | -follow-log | true | Emit all container logs. These can be noisy, so we recommend `--follow-log=false` for local development. ## Adding a new upgrade integration test All upgrade tests are defined in [test/integration/consul-container/test/upgrade](/test/integration/consul-container/test/upgrade) subdirectory. Following is a guide for adding a new upgrade test case. 1. Create consul cluster(s) with a specified version. Some utility functions are provided to make a single cluster or two peered clusters: ```go // NewCluster creates a single cluster cluster, _, _ := libtopology.NewCluster(t, &libtopology.ClusterConfig{ NumServers: 1, NumClients: 1, BuildOpts: &libcluster.BuildOptions{ Datacenter: "dc1", ConsulVersion: utils.LatestVersion, }, }) ``` Or ```go // BasicPeeringTwoClustersSetup creates two peered clusters, named accpeting and dialing accepting, dialing := libtopology.BasicPeeringTwoClustersSetup(t, utils.LatestVersion, false) ``` Some workloads may require extra resources. They should be created in this setup section. For example, [https://github.com/hashicorp/consul-enterprise/blob/19e515db29541132dbbda73efb7a458cd29d705f/test/integration/consul-container/test/upgrade/peering_http_test.go#L30-L41](this peering test creates a second static-server). 2. Verify the workload ```go libassert.HTTPServiceEchoes(t, "localhost", port, "") libassert.AssertFortioName(t, fmt.Sprintf("http://localhost:%d", appPort), "static-server-2-v2", "") ``` 3. Call the `StandardUpgrade` method and check that the upgrade succeeded. We also restart the Envoy proxy to make sure the upgraded agent can generate the correct Envoy configurations. ```go require.NoError(t, cluster.StandardUpgrade(t, context.Background(), utils.TargetVersion)) require.NoError(t, staticServerConnectProxy.Restart()) require.NoError(t, staticClientConnectProxy.Restart()) ``` 4. Verify the workload from step 3 again ```go libassert.HTTPServiceEchoes(t, "localhost", port, "") libassert.AssertFortioName(t, fmt.Sprintf("http://localhost:%d", appPort), "static-server-2-v2", "") ``` For longer verifications, it can be nice to make a local function instead: ```go tests := func() { libassert.HTTPServiceEchoes(t, "localhost", port, "") libassert.AssertFortioName(t, fmt.Sprintf("http://localhost:%d", appPort), "static-server-2-v2", "") } tests() // ... do upgrade tests() ``` ### Errors Test Cases There are some caveats for special error handling of versions prior to `1.14`. Upgrade tests for features such as peering had API changes that return an error if an upgrade is attempted, and should be accounted for in upgrade tests. If running upgrade tests for any version before `1.14`, the following lines of code need to be added to skip it or it will not pass. ```go fromVersion, err := version.NewVersion(utils.LatestVersion) require.NoError(t, err) if fromVersion.LessThan(utils.Version_1_14) { t.Skip("...") } ``` See example [here](https://github.com/hashicorp/consul-enterprise/blob/005a0a92c5f39804cef4ad5c4cd6fd3334b95aa2/test/integration/consul-container/test/upgrade/peering_control_plane_mgw_test.go#L92-L96) To write tests for bugs found during upgrades, see example on how to add a testcase for those scenarios [here](./fullstopupgrade_test.go). ## FAQS **Q.** Are containers' ports (e.g., consul's 8500, envoy sidecar's admin port or local upstream port) exposed on the docker host? \ **A.** Yes, they are exposed. However, they are exposed through a [pod container](https://github.com/hashicorp/consul/blob/57e034b74621180861226a01efeb3e9cedc74d3a/test/integration/consul-container/libs/cluster/container.go#L132). That is, a consul agent and the envoy proxy containers registered with the agent share the [same Linux network namespace (i.e., they share `localhost`)](https://github.com/hashicorp/consul/blob/57e034b74621180861226a01efeb3e9cedc74d3a/test/integration/consul-container/libs/cluster/app.go#L23-L30) as the pod container. The pod container use the same prefix as the consul agent in its name. **Q.** To troubleshoot, how can I send API request or consul command to the deployed cluster? \ **A.** To send an API request or command to the deployed cluster, ensure that a cluster, services and sidecars have been created. See example below: ```go cluster, _, _ := topology.NewCluster() clientService := createServices(t, cluster) _, port := clientService.GetAddr() _, adminPort := clientService.GetAdminAddr() ... time.Sleep(900 * time.Second) fmt.Println(port, adminPort) ``` Then in your terminal `docker ps -a | grep consul` to get the running services and cluster. Exec in the cluster and run commands directly or make API request to `localhost:port` to relevant service or `localhost:adminPort` for envoy. **Q.** To troubleshoot, how can I access the envoy admin page? \ **A.** To access envoy admin page, ensure that a cluster, services and sidecars have been created. Then get the adminPort for the client or server sidecar. See example on how to get the port above. Then navigate to a browser and go to the url `http://localhost:adminPort/` **Q.** My test is stuck with the error "could not start or join all agents: container 0: port not found"? \ **A.** Simply re-run the tests. If the error persists, prune docker images `docker system prune`, run `make dev-docker`, then re-run tests again. **Q.** How to clean up the resources created the upgrade test? **A.** Run the command `docker ps | grep consul` to find all left over resources, then `docker stop {CONTAINER_ID} && docker rm {CONTAINER_ID}` --- ### Overview (`ui/packages/consul-ui/docs/a11y-audit/README.md`) # Consul UI accessibility audit Tracks a systematic a11y audit of consul-ui, broken into independent, per-section tasks. **Audit only** — findings are documented here with suggested fixes, but no fixes are applied as part of this work. ## Method (applies to every task file) - **Automated:** two independent rule engines are run against each representative page/state, since they catch different things: - Chrome DevTools Lighthouse accessibility audit (axe-core-based). - IBM's `accessibility-checker` (the open-source engine behind DevTools' "Accessibility Assessment" panel — that panel and "Screen Reader Simulator" themselves aren't drivable by any available automation tool, since they're proprietary Chrome-extension UI with no exposed API; running the engine directly via its Node API is the closest equivalent). Installed standalone in the scratchpad dir (`npm install accessibility-checker`), *not* added as a project dependency. Run via a small script calling `aChecker.getCompliance(url, label)` against the dev server. - In this pass IBM's checker surfaced 3 concrete bugs axe/Lighthouse missed entirely (findings #5–#7 in [01-shared-chrome.md](01-shared-chrome.md)), plus independently confirmed the contrast finding (#1) both tools agree on. Worth running both engines on every task, not just one. **Reproducing the IBM scan** (scratchpad install, not a project dependency — recreate this each session, it doesn't persist): ```bash mkdir a11y-ibm && cd a11y-ibm && npm init -y && npm install accessibility-checker ``` ```js // scan.js const aChecker = require("accessibility-checker"); (async () => { const { report } = await aChecker.getCompliance("http://localhost:4200/ui/dc1/services", "services"); for (const it of report.results) { if (it.level === "violation" || it.level === "potentialviolation") { console.log(`[${it.level}] ${it.ruleId} :: ${it.message}`); console.log(" path:", it.path && it.path.dom); } } await aChecker.close(); })(); ``` Run with `node scan.js`. Swap the URL/label per page being audited. - **Manual keyboard:** Tab/Shift+Tab/Enter/Escape/Arrow-key traversal, checking focus order, visible focus indication, keyboard operability of all interactive elements (dropdowns, modals, tables, forms), and no keyboard traps. - **Screen-reader-equivalent spot checks:** inspection of the accessibility tree (roles, accessible names, states, live regions) that Chrome DevTools exposes. **This is not a live run of VoiceOver/NVDA/JAWS** — no screen reader automation is available in this environment. Tree data is a good proxy for what would be announced, but doesn't substitute for a real AT pass before shipping fixes. Findings use axe's severity vocabulary: **Critical / Serious / Moderate / Minor**. ## Environment used Dev server at `localhost:4200`, with `packages/consul-ui/config/environment.js` `operatorConfig` set to `ACLsEnabled: true, NamespacesEnabled: true, PeeringEnabled: true, PartitionsEnabled: true` (already the case on this branch), `V2CatalogEnabled: false`, `HCPEnabled: false`. The V2 catalog / HCP shell is a different application mode, not just extra routes, and is **out of scope** for this pass. Run with `pnpm start` (the mock API, see [mock-api](../../mock-api)) — export `CONSUL_SERVICE_MIN=2` first so the randomly-generated service count can never collapse to a single, non-mesh service (see [task-4-mock-data-plan.md](task-4-mock-data-plan.md) for why that matters). A stable `backend` service with a sidecar proxy — real `Upstreams` and `Expose.Paths` — is now always present in the services list regardless of that random count, so `dc.services.instance.upstreams`/`.exposedpaths` have a reliable, reproducible target to audit against. ## Tasks | # | Task | Routes | Status | File | |---|------|--------|--------|------| | 1 | Shared chrome & global patterns | app chrome, `settings`, `unavailable`, `notfound` | Complete (7 findings) | [01-shared-chrome.md](01-shared-chrome.md) | | 2 | Overview | `dc.show`(`.serverstatus`/`.cataloghealth`/`.license`) | Complete (1 new finding + confirmed recurrences) | [02-overview.md](02-overview.md) | | 3 | Services (list & detail) | `dc.services`(`.show`.*), `dc.routing-config` | Complete (3 new findings) | [03-services.md](03-services.md) | | 4 | Service instance detail | `dc.services.instance`.* | Complete (1 finding + confirmed recurrences on all 5 sub-tabs) | [04-service-instance.md](04-service-instance.md) | | 5 | Nodes | `dc.nodes`(`.show`.*) | Complete (1 high-reach finding) | [05-nodes.md](05-nodes.md) | | 6 | Key/Value | `dc.kv`.* | Complete (2 minor findings) | [06-kv.md](06-kv.md) | | 7 | Intentions (top-level) | `dc.intentions`.* | Complete (1 finding, upstream HDS) | [07-intentions.md](07-intentions.md) | | 8 | Access Controls — Tokens | `dc.acls.tokens`.* | Complete (no new findings; 1 tool false-positive documented) | [08-acls-tokens.md](08-acls-tokens.md) | | 9 | Access Controls — Policies | `dc.acls.policies`.* | Complete (no new findings) | [09-acls-policies.md](09-acls-policies.md) | | 10 | Access Controls — Roles | `dc.acls.roles`.* | Complete (no new findings) | [10-acls-roles.md](10-acls-roles.md) | | 11 | Access Controls — Auth Methods | `dc.acls.auth-methods`.* | Complete (no new findings; corroborates #3) | [11-acls-auth-methods.md](11-acls-auth-methods.md) | | 12 | Peers | `dc.peers`.* | Complete (no new findings; `.show` blocked on no peered clusters in mock data) | [12-peers.md](12-peers.md) | | 13 | Admin Partitions | `dc.partitions`.* | Complete (no new findings) | [13-partitions.md](13-partitions.md) | | 14 | Namespaces | `dc.nspaces`.* | Complete (1 finding, 3rd occurrence of a recurring pattern) | [14-namespaces.md](14-namespaces.md) | Task 1 (shared chrome) is audited first since its components (header, side nav, tables, pagination, modals, notifications) are reused across every other section — findings there apply everywhere and don't need to be re-logged per-section. ## Summary — all 14 tasks All tasks are complete except Task 12, which is partial: `dc.peers.show` has no peered cluster to open in this dataset. (Task 4 was in the same state — `dc.services.instance`'s `.upstreams`/`.exposedpaths`/`.addresses`/`.metadata` tabs needed mesh mock data before they could be audited — but that's now resolved; see [task-4-mock-data-plan.md](task-4-mock-data-plan.md) and [04-service-instance.md](04-service-instance.md).) Everything else was fully reachable. **Recurring patterns worth fixing once, centrally, rather than per-instance:** 1. **`aria-label`/`aria-labelledby` on an element with no compatible role** (the attribute is silently dropped because the element's implicit role is `generic`, which doesn't support naming) — found independently 4 times: `
` wrappers ([02-overview.md](02-overview.md) #1), HDS's own `Hds::Alert` ([07-intentions.md](07-intentions.md) #1, recurring again on the service-instance Exposed Paths tab's intro alert — [04-service-instance.md](04-service-instance.md)), and the ACL ruleset badge ([14-namespaces.md](14-namespaces.md) #1, the one instance with a confirmed real information loss). Worth an `ember-template-lint` rule if one doesn't already exist for this. 2. **HDS's `{{hds-tooltip}}` modifier makes any host element tabbable with no widget role** ([01-shared-chrome.md](01-shared-chrome.md) #7) — recurred in nearly every task (Overview, Services, Service instance, Nodes, Peers). Upstream in `@hashicorp/design-system-components`; consul-ui uses it 30+ places. 3. **`ConsulCopyButton`'s `aria-label` replaces its visible value instead of including it** ([05-nodes.md](05-nodes.md) #1) — WCAG 2.5.3 Label in Name, 11 usage sites app-wide. Single highest-reach fix in the whole audit: one component change covers all 11. 4. **The side-nav `