Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update byoc doc #116

Merged
merged 4 commits into from
Jan 21, 2022
Merged

update byoc doc #116

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4ea82eb
update byoc doc
xytian315 Jan 11, 2022
c06ce11
update install.md
xytian315 Jan 14, 2022
a7f7bb7
update magtape-init to not to check secret updated-by-pod label when …
xytian315 Jan 14, 2022
3c8ef3d
change the format after runing black to lint python
xytian315 Jan 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 40 additions & 24 deletions docs/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,21 @@ We've tried to build a decent amount of flexibility into MagTape. While the simp

NOTE: The following environment variable are defined in the `magtape-env-cm.yaml` manifest and can be used to customize MagTape's behavior.

| Variable | Description | Values |
|--- |--- |--- |
| `FLASK_ENV` | The operation environment for Flask | `production` or `development` |
| `MAGTAPE_DENY_LEVEL` | Controls the level of denial for checks. Please see section above on Deny Level | `LOW`, `MED`, or `HIGH` |
| `MAGTAPE_LOG_LEVEL` | The log level to use | `INFO` or `DEBUG` |
| `MAGTAPE_CLUSTER_NAME` | The name of the Kubernetes Cluster where the webhook is deployed | `test-cluster` |
| `MAGTAPE_TLS_SECRET` | **OPTIONAL** - Overrides the default secret (`magtape-tls`) for BYOC (Bring Your Own Cert) scenarios| <name_of_secret> (STRING) |
| `MAGTAPE_K8S_EVENTS_ENABLED` | Controls whether or not Kubernetes events are generated within the target namespace for policy failures | `TRUE` or `FALSE` |
| `MAGTAPE_SLACK_ENABLED` | Controls whether or not the webhook sends Slack notifications | `TRUE` or `FALSE` |
| `MAGTAPE_SLACK_PASSIVE` | Controls whether or not Slack alerts are sent for checks that fail, but aren't denied due to the DENY_LEVEL setting | `TRUE` or `FALSE` |
| `MAGTAPE_SLACK_WEBHOOK_URL_BASE` | **OPTIONAL** - Overrides the base domain (`hooks.slack.com`) for the Slack Incoming Webhook URL. Used for airgapped environments where a forwarding/proxying service may be needed | `slack-proxy.example.com` |
| `MAGTAPE_SLACK_WEBHOOK_URL_DEFAULT` | The URL for the Slack Incoming Webhook. | `https://hooks.slack.com/services/XXXXXXXX/XXXXXXXX/XXXXXXXXXXXXXXXXXX` |
| `MAGTAPE_SLACK_USER` | The user the Slack alerts should be sent as | `mtbot` |
| `MAGTAPE_SLACK_ICON` | The emoji to use for the user icon in the alert | `:magtape:` |
| `OPA_BASE_URL` | The base URL used to contact the OPA API | `http://localhost:8181` |
| `OPA_K8S_PATH` | The common path to reference all Kubernetes based OPA policies | `/v0/data/magtape` |
| Variable | Description | Values |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `FLASK_ENV` | The operation environment for Flask | `production` or `development` |
| `MAGTAPE_DENY_LEVEL` | Controls the level of denial for checks. Please see section above on Deny Level | `LOW`, `MED`, or `HIGH` |
| `MAGTAPE_LOG_LEVEL` | The log level to use | `INFO` or `DEBUG` |
| `MAGTAPE_CLUSTER_NAME` | The name of the Kubernetes Cluster where the webhook is deployed | `test-cluster` |
| `MAGTAPE_K8S_EVENTS_ENABLED` | Controls whether or not Kubernetes events are generated within the target namespace for policy failures | `TRUE` or `FALSE` |
| `MAGTAPE_SLACK_ENABLED` | Controls whether or not the webhook sends Slack notifications | `TRUE` or `FALSE` |
| `MAGTAPE_SLACK_PASSIVE` | Controls whether or not Slack alerts are sent for checks that fail, but aren't denied due to the DENY_LEVEL setting | `TRUE` or `FALSE` |
| `MAGTAPE_SLACK_WEBHOOK_URL_BASE` | **OPTIONAL** - Overrides the base domain (`hooks.slack.com`) for the Slack Incoming Webhook URL. Used for airgapped environments where a forwarding/proxying service may be needed | `slack-proxy.example.com` |
| `MAGTAPE_SLACK_WEBHOOK_URL_DEFAULT` | The URL for the Slack Incoming Webhook. | `https://hooks.slack.com/services/XXXXXXXX/XXXXXXXX/XXXXXXXXXXXXXXXXXX` |
| `MAGTAPE_SLACK_USER` | The user the Slack alerts should be sent as | `mtbot` |
| `MAGTAPE_SLACK_ICON` | The emoji to use for the user icon in the alert | `:magtape:` |
| `OPA_BASE_URL` | The base URL used to contact the OPA API | `http://localhost:8181` |
| `OPA_K8S_PATH` | The common path to reference all Kubernetes based OPA policies | `/v0/data/magtape` |

## Installation

Expand All @@ -31,11 +30,11 @@ The kustomize layout uses overlays to allow for flexibility in configuration (ie

You can find some generic examples of using kustomize overlays to manage per environment configuration in the following directories:

| DIRECTORY | DESCRIPTION |
|--- |--- |
| `deploy/manifests` | The base YAML manifests |
| `deploy/overlays/development` | Development environment specific substitutions |
| `deploy/overlays/production` | Production environment specific substitutions |
| DIRECTORY | DESCRIPTION |
| ----------------------------- | ---------------------------------------------- |
| `deploy/manifests` | The base YAML manifests |
| `deploy/overlays/development` | Development environment specific substitutions |
| `deploy/overlays/production` | Production environment specific substitutions |

Once the proper edits have been made you can generate the YAML manifests:

Expand Down Expand Up @@ -72,13 +71,30 @@ NOTE: A TLS Cert and Key need to be generated for the Webhook. MagTape has an in

By default MagTape will handle creation and rotation of the required TLS cert/key automatically. In cases where you need to BYOC, you can adjust the configuration.

### Specify a different secret name
### Create the secret

Reference the `MAGTAPE_TLS_SECRET` option in the [configuration options](#configuration-options) section.
Create the secret name called `magtape-tls` with the annotation `magtape-byoc` in the `magtape-system` namespace. The `cert.pem`, `key.pem` must be provided in the data field of the secret. This secret must exist prior to install MagTape.
phenixblue marked this conversation as resolved.
Show resolved Hide resolved

The following YAML contains an example of the secret
```yaml
apiVersion: v1
data:
cert.pem: "..."
key.pem: "..."
kind: Secret
metadata:
annotations:
magtape-byoc: ""
labels:
app: magtape
name: magtape-tls
namespace: magtape-system
type: tls
```

### Root CA

The VWC (Validating Webhook Configuration) needs to be configured with a cert bundle that includes the CA that signed the certificate and key used to secure the MagTape API. For now MagTape assumes this CA certificate exists in the `magtape-tls-ca` secret deployed within the `magtape-system` namespace. This secret must exist prior to installing MagTape.
The VWC (Validating Webhook Configuration) needs to be configured with a cert bundle that includes the CA that signed the certificate and key used to secure the MagTape API. For now MagTape assumes this CA certificate exists in the `magtape-tls-ca` secret deployed within the `magtape-system` namespace. The `rootca.pem` must be provided in the data field of the secret. This secret must exist prior to install MagTape.
phenixblue marked this conversation as resolved.
Show resolved Hide resolved

No validation is done currently to ensure the specified CA actually signed the cert and key used to secure MagTape's API. We plan to add this validation in a future release.

Expand Down