Deploy using a Helm Chart
If your applications are deployed using Helm, Corsha provides a Helm Chart to deploy the Corsha Gatekeeper in front of your API Servers. After the Corsha Gatekeeper is deployed, targeted API endpoints will be Corsha-Protected.
The Gatekeeper's Helm chart is named corsha/proxy for backward compatibility. All references to "proxy" in commands and configuration refer to the Corsha Gatekeeper.
Secret Material
Corsha Helm Charts contain sensitive values, and must use a secrets management solution. Our documentation uses Helm Secrets, but your Corsha TPOC is ready to assist with integrating another secrets management method.
Deploying the Corsha Gatekeeper
This section will guide you through the required steps to deploy the Corsha Gatekeeper. To do so we will need to:
- Create and modify the Corsha Gatekeeper's configuration.
- Install the Corsha Gatekeeper using your configuration parameters via Helm.
If you need to obtain the Corsha Gatekeeper or have any questions regarding the deployment of the Corsha Gatekeeper, reach out to your Corsha TPOC.
Gatekeeper Configuration
The Corsha Gatekeeper Helm Chart requires configuration values for your environment. In this section we will guide you through creating two important configuration files for the Corsha Gatekeeper.
values.yaml: Plain text configuration data.secrets.yaml: Encrypted configuration data for credentials and certificates.
Local Environment Setup
To organize all the charts you are going to configure, let's create a directory for each component; here it's the corsha-gatekeeper:
mkdir corsha-gatekeeper
cd corsha-gatekeeper
Values Configuration
Below is a sample content for a yaml file values.yaml you need to create in corsha-gatekeeper to configure the Corsha Gatekeeper. Note, the sample content is configured so TLS termination is not done by the Gatekeeper. If you would like to configure TLS Termination at the Gatekeeper, see the TLS Termination documentation.
For more documentation on the configuration values, please see the README provided with the Corsha Gatekeeper Helm Chart tarball; this can be downloaded from Artifactory here.
The README contains a detailed list of all configurable properties. Open up this file as you are setting up your yaml files.
The Corsha Auth Server proxy-auth domain can be retrieved from the Auth Server proxy-auth URL provided by Corsha in the deployment documentation you received. Make sure to configure authserver.host with the Auth Server proxy-auth domain (the URL with the protocol/scheme section removed) not the full URL.
global:
TLD: <tld for the service>
authserver:
host: "auth-server-<NAMESPACE>-paas-proxy-auth.corshatech.net" # replace with the Auth Server proxy-auth domain
port: 443
timeout: 30s
http:
proxies:
- name: service1
domain: "service1.foo.com"
upstream:
host: "serv1.service1.local"
protocol: "HTTPS"
port: 443
Proxy Secret Configuration
After adding non-sensitive Helm configuration values to a values.yaml file, use sops to store secret Helm configuration values in an encrypted format in a secrets.yaml file.
To encrypt the secret values, use the fingerprint of the PGP key provided in your Deployment Guide:
$ gpg --list-secret-keys
/home/ubuntu/.gnupg/pubring.kbx
-------------------------------
sec rsa4096 2022-01-10 [SC] [expires: 2023-01-10]
E989D51B08C9C5BE0DD5CCA64F3A2320CA653FBB
uid [ultimate] example (Used for Helm secrets)
The hexadecimal string is the fingerprint that we will use to identify which key is encrypting our Helm secrets.
To create the Helm secrets file and replace the default values with the values we need to store in encrypted format, run the following:
sops --pgp <fingerprint> secrets.yaml
This will open an editor in which we can insert our secret values to be encrypted. Remove any pre-populated content from the editor and add the following values, edited with your secret values. For more information on configuration values, check the README.md mentioned above or the Helm Chart Values Guide.
Lastly, Gatekeepers must be seeded with a proxySecret variable saved in the secrets.yaml file. Use the appropriate command in the Generating A Proxy Secret Guide to generate the proxySecret in the following values.
If there are any secret elements or parameters in http.proxies[], then the entire http.proxies[] configuration must be stored in the secrets.yaml file. Helm cannot merge lists from multiple values/secrets files. If you try to add some http.proxies[] elements or parameters to the values.yaml file and some to the secrets.yaml file, the http.proxies[] list will be misconfigured.
imageCredentials:
registry: <Artifactory registry>
username: <Artifactory username>
password: <Artifactory password>
proxySecret: < Generated via the "Generating A Proxy Secret Guide" referenced above >
authserver:
# These certs are required for MTLS with the Corsha Auth Server regardless of whether or not TLS termination at the Gatekeeper is enabled
tls:
cert: |
-----BEGIN CERTIFICATE-----
<omitted>
-----END CERTIFICATE-----
key: |
-----BEGIN EC PRIVATE KEY-----
<omitted>
-----END EC PRIVATE KEY-----
http:
proxies:
- name: service1
domain: "service1.foo.com"
upstream:
host: "serv1.service1.local"
protocol: HTTPS
port: 443
If you later need to make updates to this secrets.yaml file that was created, you can simply run sops to edit the encrypted values.
sops secrets.yaml
Install the Corsha Gatekeeper
Add the Corsha Helm repository, if you have not already, using the username and password you have been provided in your Deployment Guide. If this command returns "repository name (corsha) already exists" then you have already logged in to the repository.
helm repo add corsha https://corsha.jfrog.io/corsha/corsha --username #<Artifactory username>
Install the Gatekeeper's chart using Helm, using the version provided by your Corsha TPOC:
helm -n $NS secrets install gatekeeper corsha/proxy -f values.yaml -f secrets.yaml --verify --version <version>
Verify the Corsha Gatekeeper Installation
Make sure that there is a Gatekeeper pod running in your namespace. You can do so by running the command below, with output also shown as an example.
$ kubectl -n $NS get pods
NAME READY STATUS RESTARTS AGE
proxy 1/1 Running 0 38s