Route Updates

If you have route updates that need to be made for one of your services, you can either have them completed as part of a deployment or separately. Route updates are submitted as a pull request to the HAPS platform team to complete.

Separate Route Update

From a ticket for that service in the Jira project space, use the "PO: <Project> Route Update (non-release)" automation. This will create the RM ticket for you with the route template. Fill in the basic information that you need.
In the MACM project in code repo, create a branch named as the RM ticket name (example: DHAPI-1117/dhapi_portal_staff_route) within the correct repo depending on what kind of route update you need (see Choosing the Repository). Create the branch from sqa for SQA or from prod for production.
Make the changes (see Making the Change). DO NOT CREATE A PULL REQUEST.
Share the RM ticket with the RM. They will review the ticket, create the appropriate ticket for the HAPS team, create the PR that is linked to that new ticket for the HAPS team and submit it.
- The PR will show up on both the RM ticket and the ticket for the HAPS team.
Once the ticket is merged and completed, it will be closed out and the RM will close out the linked RM ticket.

Example

DHAPI-1117 (RM ticket) / NGD-34017 (HAPS team ticket). See Worked Example: DHAPI-1117 for a step-by-step walkthrough.

Route Update with a Deployment

From a ticket for that service in the Jira project space, use the "PO: <Project> Deploy Task (templated)" automation. This will create the RM deploy ticket for you. At the top of the ticket, there is a space asking if a route update is needed. Type Y and fill in the basic information that you need.
In the MACM project in code repo, create a branch named as the RM ticket name (example: DHAPI-1117/dhapi_portal_staff_route) within the correct repo depending on what kind of route update you need (see Choosing the Repository). Create the branch from sqa for SQA or from prod for production.
Make the changes (see Making the Change). DO NOT CREATE A PULL REQUEST.
Share the RM ticket with the RM. They will review the ticket and create the appropriate ticket for the HAPS team. As part of preparing the deployment ticket, they will create the PR and link it to the route subtask ticket for the HAPS team. They will submit the deployment ticket.
- The PR will show up on both the RM ticket and the route subtask ticket for the HAPS team.
Once the deployment is completed, which includes the route change being merged and completed, it will be closed out and the RM will close out the linked RM ticket.

Choosing the Repository

Routes live in the MACM project as JSON files, which Terraform loads into Consul. There is one repo per route type and environment, and the repo you change (not the contents of the file) decides which gateway serves the route.

Route type SQA (branch from sqa) Production (branch from prod)

Route type	SQA (branch from `sqa`)	Production (branch from `prod`)
Staff route Served on the staff gateway: `staff.apps-staging.va.gov` in SQA and `staff.apps.va.gov` in production.	vaec-map-routes-staging-tf-staff	vaec-map-routes-prod-tf-staff
API gateway route Served on the Veteran-facing gateway: `veteran.apps-staging.va.gov` in SQA and `veteran.apps.va.gov` in production.	vaec-map-routes-staging-tf-apigateway	vaec-map-routes-prod-tf-apigateway

Staff route
Served on the staff gateway: staff.apps-staging.va.gov in SQA and staff.apps.va.gov in production.

vaec-map-routes-staging-tf-staff

vaec-map-routes-prod-tf-staff

API gateway route
Served on the Veteran-facing gateway: veteran.apps-staging.va.gov in SQA and veteran.apps.va.gov in production.

vaec-map-routes-staging-tf-apigateway

vaec-map-routes-prod-tf-apigateway

A service that has to be available on both gateways needs a route file in both repos for that environment. For example, dhapi-partner-portal-web got its API gateway route in DHAPI-1078 and its staff route in DHAPI-1117.
Not sure which gateway your service uses? Check whether the server URLs in its OpenAPI contract use a staff.apps or a veteran.apps host, or search the repos above for its existing route file.

The staging repos also have long-lived branches for other staging namespaces (sts, int, st2e, and others). Use sqa for SQA.

The other vaec-map-routes-* repos in MACM are not where route updates go. The parent -tf repos (for example vaec-map-routes-staging-tf) pull in the repos above as git submodules, -tf-environment and -tf-apache hold environment and Apache settings, the sandbox repos are for the sandbox environment, and the repos without -tf have not been updated since 2021. Ask the RM if you are unsure.

Making the Change

Each route is a JSON file in the repo’s 3.0/services/ folder, usually named after the service and its major version (for example 3.0/services/dhapi-partner-portal-web-v1.json).

To change an existing route, edit the service’s existing file.
To add a route, copy the file of a similar service and adjust it. Each file has one location, so a service with more than one path has more than one file (for example url-shortener-service-v1.json and url-shortener-service-v1-go.json).

This is the file that DHAPI-1117 added to vaec-map-routes-staging-tf-staff:

{
  "location": "/dhapi-portal/",
  "service": "dhapi-partner-portal-web-v1.sqa",
  "redirect": "off",
  "request_headers": "on",
  "headers": {
    "X-Real-IP": "$remote_addr",
    "X-Forwarded-For": "$proxy_add_x_forwarded_for",
    "X-Forwarded-Server": "$http_host",
    "X-Forwarded-Host": "$http_host"
  }
}

Field What it does

Field	What it does
`location`	The URL path on the gateway. Here, `/dhapi-portal/` on the staff gateway, so `staff.apps-staging.va.gov/dhapi-portal/`.
`service`	The Kubernetes service that receives the traffic, written as `<service>.<namespace>`. This is normally `.sqa` for SQA and `.prod` for production (for example `callback-service-v1.prod`).
`headers`	Headers passed to the service. These differ between services, so copy them from a similar route.
Other fields	Settings such as `redirect`, `request_headers`, `rewrite`, and `port` vary by route. Copy them from a similar route. `rewrite` changes the path before it is forwarded. For example, `url-shortener-service-v1-go.json` serves `/go/` and rewrites it to `/urlshortener/v1`.

location

The URL path on the gateway. Here, /dhapi-portal/ on the staff gateway, so staff.apps-staging.va.gov/dhapi-portal/.

service

The Kubernetes service that receives the traffic, written as <service>.<namespace>. This is normally .sqa for SQA and .prod for production (for example callback-service-v1.prod).

headers

Headers passed to the service. These differ between services, so copy them from a similar route.

Other fields

Settings such as redirect, request_headers, rewrite, and port vary by route. Copy them from a similar route. rewrite changes the path before it is forwarded. For example, url-shortener-service-v1-go.json serves /go/ and rewrites it to /urlshortener/v1.

The RM and the HAPS team review the change before it is merged.

Worked Example: DHAPI-1117

dhapi-partner-portal-web already had an API gateway route in SQA from DHAPI-1078 and needed a staff route as well.

The PO answered the SQA configuration questions at the top of DHAPI-1117:
```
Are Vault changes needed? N
Are Route changes needed? Y
Are any infrastructure changes necessary (Database creation/changes, ApiGateway route changes)? N
```
Answer Y to the route question for a change in either route repo. DHAPI-1078, which added the API gateway route file, also answered N to the infrastructure question.
Because it was a staff route in SQA, the branch DHAPI-1117/dhapi_portal_staff_route was created from sqa in vaec-map-routes-staging-tf-staff.
The only change was the new 3.0/services/dhapi-partner-portal-web-v1.json file shown in Making the Change. The PO did not open a pull request.
The RM created the HAPS ticket NGD-34017 (SQA: dhapi-partner-portal-web route update) and opened PR #730 (NGD-34017: Add DHAPI Portal route) from that branch into sqa.
The HAPS team approved the PR and it was merged. NGD-34017 was closed, and then the RM closed DHAPI-1117.