TODO: These instructions are pretty vague, but changed dramatically with VAEC. Adding high level notes for now, and need to come back to doc this better the next time we add a new backend.

The following steps must be preformed to fully add in a new external service integration

  1. Establish connectivity

  2. Forward Proxy

  3. SSL Keys ( roles and meta additions )

  4. Security Group / ELB config

  5. Prometheus alerts

  6. Pager Duty routing

  7. Rails config

Establish connectivity

From a fwdproxy instance on a given environment, try to reach the new service via whatever endpoint you have with curl. Anything over port 443 should work, but alternate ports need an ESECC request.

Forward Proxy

Once you have verified connectivity, add entries to the forward proxy deployments: ansible/deployment/config/fwdproxy-<env>

SSL Keys

Many backend VA services require the use of a client SSL certificate and key for authentication. Securely generate a private key and certificate using the instructions at: docs/StandardOperatingProcedures/CreatingVASignedSSLCertificate.md. Add the cert as a Jinja2 template to ansible/deployment/config/fwdproxy/, and add the private key to AWS Parameter Store with a name like /devops/certificates/<service>.key More recently, key storage has moved to Credstash, so please check with an engineer on the appropriate private key storage service.

NOTE: Currently, we don't impose CN restrictions on the SSL certs for new External Service Integration

Security Group / ELB config

Validate the the ports assigned for the forward proxy are listed in the listener_ports variable in terraform/environments/<env>/main.tf. The port should match what is in the Forward Proxy config above.

Prometheus Alerts

Add in configuration for the forward proxy backend to ansible/roles/prometheus-server/templates/external_service.rules

Pager Duty Routing

Create a new PagerDuty service in terraform/environments/dsva-pagerduty/external_services.tf. Retrieve the Prometheus integration key from the UI and store the key in AWS Parameter Store under /devops/pagerduty/external_service. Modify ansible/roles/prometheus-server/templates/alertmanager.yml.j2 to route messages to the pagerduty service

Rails Config

Add in the require host redirects in ansible/deployment/vets-api/<env>-settings.local.yml.j2