Skip to content

Commit

Permalink
Merge pull request #18 from sensu/release/0.4.0
Browse files Browse the repository at this point in the history 
preparing for release/0.4.0
  • Loading branch information
Jef Spaleta authored Feb 1, 2021
2 parents a028020 + 0f7921e commit e15e6e3
Show file tree
Hide file tree
Showing 3 changed files with 67 additions and 58 deletions.
86 changes: 43 additions & 43 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
# SensuFlow Github Action
The Github action for SensuFlow, a git based approach to managing Sensu resources.
# SensuFlow GitHub Action
The GitHub Action for SensuFlow, a git-based approach to managing Sensu resources.

## Introduction
This Github action will allow you to manage Sensu resources for multiple Sensu namespaces as part Github facilitated CI/CD workflows.
This GitHub Action will allow you to manage Sensu resources for multiple Sensu namespaces as part of GitHub-facilitated CI/CD workflows.

In order to use this action, you'll first need to define a Sensu user and associated role based access control. A reference RBAC policy and user definition, matching the the actions default settings is provided below as a reference.
In order to use this action, you'll first need to define a Sensu user and associated role-based access control. A reference RBAC policy and user definition matching the Action's default settings is provided below as a reference.


## How It Works
This action provides an opinionated best practises to using the `sensuctl create` and `sensuctl prune` commands in order to efficiently manage Sensu monitoring resources in one more namespaces. The action automates several resource linting actions to help ensure self-consistent monitoring resources are defined prior to updating any Sensu resources.
This Action provides an opinionated best practises to using the `sensuctl create` and `sensuctl prune` commands in order to efficiently manage Sensu monitoring resources in one or more namespaces. The Action automates several resource linting actions to help ensure self-consistent monitoring resources are defined prior to updating any Sensu resources.

This is achieved by processing a directory structure where each subdirectory is mapped to a Sensu namespace.
By default the required directory structure looks like:
By default, the required directory structure looks like:
```
.sensu/
cluster/
Expand All @@ -26,25 +26,25 @@ By default the required directory structure looks like:
mutators/
```
where `<namespace>` is a placeholder for each Sensu namespace under management. The `cluster/` directory can be used to optionally manage Sensu Cluster wide resources such as namespaces, if the Sensu RBAC profile in use allows for cluster-wide resource management.
where `<namespace>` is a placeholder for each Sensu namespace under management. The `cluster/` directory can be used to optionally manage Sensu cluster-wide resources, such as namespaces, if the Sensu RBAC profile in use allows for cluster-wide resource management.

## Setup

### Configure Sensu RBAC Profile
Below are instructions to create a RBAC profile that can be used with this action with the default settings. This profile makes use of Sensu CluserRole and ClusterRoleBindings to grant the action user access to a subset of Sensu resources cluster-wide. You may want to use a more restrictive RBAC policy to meet your security requirements.
### Configure the Sensu RBAC Profile
Below are instructions to create an RBAC profile that can be used with this Action with the default settings. This profile makes use of Sensu CluserRole and ClusterRoleBindings to grant the Action user access to a subset of Sensu resources cluster-wide. You may want to use a more restrictive RBAC policy to meet your security requirements.

You will need to run these commands in an an environment where sensuctl is pre-configured to communicate with the Sensu backend you want SensuFlow to work with.
You will need to run these commands in an environment where sensuctl is pre-configured to communicate with the Sensu backend you want SensuFlow to work with.

#### Create the sensu-flow ClusterRole
The Sensu ClusterRole defines the resource permissions the github resource will need.
The Sensu ClusterRole defines the resource permissions the GitHub resource will need.
```
$ sensuctl cluster-role create sensu-flow \
--resource namespaces,roles,rolebindings,assets,handlers,checks,hooks,filters,mutators,secrets \
--verb get,list,create,update,delete
```

#### Create the sensu-flow ClusterRoleBinding
The Sensu ClusterRoleBinding connects the ClusterRole to a group of users
The Sensu ClusterRoleBinding connects the ClusterRole to a group of users.
```
$ sensuctl cluster-role-binding create sensu-flow \
--cluster-role sensu-flow \
Expand All @@ -71,8 +71,8 @@ $ sensuctl user create sensu-flow \
```

### Configure SensuFlow Github action
In order to make use of this Github action you will need to use it as part of a github action workflow YAML definition. GitHub action workflow definitions are placed in `.github/workflows/` in your repository and must exist in the default branch. Please see the Github action documentation for specifics.
### Configure the SensuFlow GitHub Action
In order to make use of this GitHub Action you will need to use it as part of a GitHub Action workflow YAML definition. GitHub Action workflow definitions are placed in `.github/workflows/` in your repository and must exist in the default branch. Please see the GitHub Action documentation for specifics.


The action requires 3 configuration options to be defined:
Expand All @@ -81,15 +81,15 @@ sensu_backend_url
sensu_user
sensu_password
```
All other configuration options are considered optional
All other configuration options are considered optional.

You will also want to considering GitHub secrets for sensitive information used in the action configuration. At a minimum you will want to consider using Github secrets for the `sensu_user` and `sensu_password`.
You will also want to consider using GitHub secrets for sensitive information used in the Action configuration. At a minimum, you will want to consider using GitHub secrets for the `sensu_user` and `sensu_password`.

### Verifying Configuration
Below is a working example that will run the SensuFlow Github action when pushing to main branch or when a main branch pull-request is created.
Below is a working example that will run the SensuFlow GitHub Action when pushing to main branch or when a main branch pull-request is created.

#### Github Action Workflow Example
Save as `.github/workflows/sensu-flow.yaml` and commit to main branch. After activating the workflow in the Github UX, this action should run for any commits into main.
#### GitHub Action Workflow Example
Save as `.github/workflows/sensu-flow.yaml` and commit to main branch. After activating the workflow in the GitHub UX, this Action should run for any commits into main.

```
name: SensuFlow CI Example
Expand All @@ -111,7 +111,7 @@ jobs:
# Step 2: use the versioned sensu/sensuflow action
- name: Sensuflow with required settings
uses: sensu/sensu-flow@0.3.0
uses: sensu/sensu-flow@0.4.0
with:
# Required configuration
# Please make use of GitHub secrets for sensitive information
Expand All @@ -125,11 +125,11 @@ jobs:
matching_condition: "== 'sensu-flow'"
```
### Your first SensuFlow workflow
### Your First SensuFlow Workflow
Now that the action is activated and configured to run on any push into the main branch, you can test it.

#### Create a test namespace
edit the file `.sensu/cluster/namespaces.yaml` in your git repository and define a Sensu namespace resource for a new testing namespace.
#### Create a Test Namespace
Edit the file `.sensu/cluster/namespaces.yaml` in your git repository and define a Sensu namespace resource for a new testing namespace.
```
---
type: Namespace
Expand All @@ -138,15 +138,15 @@ spec:
name: test-namespace
```

### Create corresponding namespace directory
### Create Corresponding Namespace Directory
```
mkdir -p .sensu/namespaces/test-namespace
touch .sensu/namespaces/.keep
```

The SensuFlow action will process the `test-namespace` directory, using resource definitions found within as a source of truth for the state of the corresponding Sensu namespace. The `.keep` file just tells git to keep the directory structure as part of the repository even if there are no files defined in it.
The SensuFlow GitHub Action will process the `test-namespace` directory, using resource definitions found within as a source of truth for the state of the corresponding Sensu namespace. The `.keep` file just tells git to keep the directory structure as part of the repository even if there are no files defined in it.

### Create initial resources in test-namespace
### Create Initial Resources in test-namespace
mkdir `.sensu/namespaces/test-namespace/checks`
edit the file `.sensu/namespaces/test-namespace/checks/hello_world.yaml`
```
Expand Down Expand Up @@ -179,9 +179,9 @@ spec:
type: pipe
```

### Commit and push changes
Once these files are in place, you can commit and push the changes back to Github. The Github SensuFlow action should trigger, and run to completion.
You can then verify using sensuctl in your administrative environment that the test-namespace exists
### Commit and Push Changes
Once these files are in place, you can commit and push the changes back to GitHub. The SensuFlow GitHub Action should trigger and run to completion.
You can then verify using sensuctl in your administrative environment that the test-namespace exists.
```
sensuctl namespace list
```
Expand All @@ -190,14 +190,14 @@ and that the namespace contains the hello-world check and the test handler
sensuctl --namespace test-namespace check list
sensuctl --namespace test-namespace handler list
```
### Delete the check from the git repository
Now delete the `hello_world.yaml` file and commit the change again. The SensuFlow action will use `sensuctl prune` to remove the check and you should be able to verify that the check no longer exists in the test-namespace.
### Delete the Check From the Git Repository
Now delete the `hello_world.yaml` file and commit the change again. The SensuFlow GitHub Action will use `sensuctl prune` to remove the check and you should be able to verify that the check no longer exists in the test-namespace.


## Github Action Configuration Reference
## GitHub Action Configuration Reference

### Namespace Resource Management
This action uses a special directory structure, mapping subdirectory names to Sensu namespaces to process. By default the directory processed is `.sensu/namespaces/` but this can be overridden in the action configuration. If this directory exists, each sub directory will be processed as separate Sensu namespace. Example directory structure:
This action uses a special directory structure, mapping subdirectory names to Sensu namespaces to process. By default the directory processed is `.sensu/namespaces/` but this can be overridden in the Action configuration. If this directory exists, each subdirectory will be processed as a separate Sensu namespace. Example directory structure:
```
.sensu
└── namespaces
Expand All @@ -218,12 +218,12 @@ This action uses a special directory structure, mapping subdirectory names to Se
└── check-status.yaml
```

Using this example, this action would process the `test-namespace`, pruning the namespace resources according to `matching_label`, `matching_condition`, and `managed_resources`settings
Using this example, this Action would process the `test-namespace`, pruning the namespace resources according to `matching_label`, `matching_condition`, and `managed_resources`settings

### Optionally Preparing namespaces
If the namespaces file (default: `.sensu/cluster/namespaces.yaml`) exists and is populated with Sensu namespace resource definitions then this action will be used to create the Sensu namespace resources defined in the file before attempting to process the namespaces directory.
### Optionally Preparing Namespaces
If the namespaces file (default: `.sensu/cluster/namespaces.yaml`) exists and is populated with Sensu namespace resource definitions, then this Action will be used to create the Sensu namespace resources defined in the file before attempting to process the namespaces directory.

Note: Namespaces are a cluster level resource, so in order to use the namespaces creation capability the sensu user will need cluser level role based access to create namespaces.
Note: Namespaces are a cluster-level resource, so in order to use the namespaces creation capability the Sensu user will need cluser-level role-based access to create namespaces.

## Configuration
### Required settings
Expand All @@ -246,26 +246,26 @@ Note: Namespaces are a cluster level resource, so in order to use the namespaces
#### namespaces_file:
description: "Optional YAML file containing Sensu namespace resources to create default '.sensu/cluster/namespaces.yml'"
#### matching_label:
description: "Option Sensu label selector, default: 'sensu.io/workflow'"
description: "Optional Sensu label selector, default: 'sensu.io/workflow'"
#### matching_condition:
description: "Option Sensu label matching condition, default: '== sensu_flow'"
description: "Optional Sensu label matching condition, default: '== sensu-flow'"
#### managed_resources:
description: 'Optional comma seperated list of managed resources, default: "checks,handlers,filters,mutators,assets,secrets/v1.Secret,roles,role-bindings,core/v2.HookConfig""'
#### disable_sanity_checks:
description: 'Optional boolean argument to to disable sanity checks default: false'


## Adapting to other CI/CD
If you would like to adapt this for other CI/CD, take a look at the sensuflow.sh script from this repositorory. The script should be self-documenting with regard to needed executable dependancies and information concerning environment variables used.
## Adapting to Other CI/CD Workflows
If you would like to adapt this for other CI/CD workflows, take a look at the sensuflow.sh script from this repositorory. The script should be self-documenting with regard to needed executable dependancies and information concerning environment variables used.

## Goals

SensuFlow is under active development, so please don't hesitate to submit issues for any enhancements you'd like to see.

The main improvements we're currently focused on at the time of this writing (H1'21) are as follows:

- Improved pre-flight tests (test Sensu endpoint liveness, verify authentication credentials, etc)
- Improved linting (label enforcement, type validation, etc)
- Improved pre-flight tests (test Sensu endpoint liveness, verify authentication credentials, etc.)
- Improved linting (label enforcement, type validation, etc.)
- Validate integrity of assets (optionally fetch all configured assets, verify SHA512 values)
- Reference testing (if a check/handler refers to assets and/or secrets, are the asset/secret resource definitions also present?)

Expand Down
20 changes: 10 additions & 10 deletions action.yml
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
# action.yml
name: 'Sensu Flow'
description: 'Manage sensu resources using sensuctl prune and create commands'
name: 'SensuFlow'
description: 'Manage Sensu resources using sensuctl prune and create commands'
inputs:
sensu_backend_url:
description: 'The Sensu backend url (alt use env SENSU_BACKEND_URL'
description: 'The Sensu backend url (alt use env SENSU_BACKEND_URL)'
required: true
sensu_user:
description: 'The Sensu user to auth (alt use env SENSU_USER'
description: 'The Sensu user to auth (alt use env SENSU_USER)'
required: true
sensu_password:
description: 'The Sensu user password (alt use env SENSU_PASSWORD'
description: 'The Sensu user password (alt use env SENSU_PASSWORD)'
required: true
configure_args:
description: "optional arguments to pass to sensuctl configure"
description: "Optional arguments to pass to sensuctl configure"
required: false
sensu_ca_string:
description: 'Optional Custom CA pem string'
Expand All @@ -21,16 +21,16 @@ inputs:
description: 'Optional Custom CA pem file location'
required: false
namespaces_dir:
description: "Optional directory to process default: 'namespaces' "
description: "Optional directory to process default: '.sensu/namespaces' "
required: false
namespaces_file:
description: "Optional YAML file containing namespace resource to create default: 'namespaces.yaml' "
description: "Optional YAML file containing namespace resource to create default: '.sensu/cluster/namespaces.yml' "
required: false
matching_label:
description: "Option Sensu label to use in label selector, default: 'sensu.io/workflow'"
description: "Optional Sensu label to use in label selector, default: 'sensu.io/workflow'"
required: false
matching_condition:
description: "Option Sensu label matching condition for label selector, default: '== sensu_flow'"
description: "Optional Sensu label matching condition for label selector, default: '== sensu-flow'"
required: false
managed_resources:
description: 'Optional comma seperated list of managed resources'
Expand Down
19 changes: 14 additions & 5 deletions sensuflow.sh
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#!/usr/bin/env ash

###
# shell script to implement sensuflow
# shell script to implement SensuFlow
## External dependancies:
# sensuctl: https://sensu.io/downloads
# yq: https://github.com/mikefarah/yq/v4
Expand All @@ -22,8 +22,9 @@
# MATCHING_CONDITION: condition to match
# DISABLE_SANITY_CHECKS: if set disable sanity checks

## Github Action Notes
# Github Actions prefaces variables with INPUT_
## GitHub Action Notes
# GitHub Actions prefaces variables with INPUT_
# This script maps INPUT_<VAR> to <VAR> for compatibility

## Read in envvars from .env from current directory
if [ -f ./.env ] ; then
Expand All @@ -32,7 +33,7 @@ fi

### Setup envvar values, including fallback defaults where needed
: ${MATCHING_LABEL:=${INPUT_MATCHING_LABEL:="sensu.io/workflow"}}
: ${MATCHING_CONDITION:=${INPUT_MATCHING_CONDITION:="== sensu_flow"}}
: ${MATCHING_CONDITION:=${INPUT_MATCHING_CONDITION:="== sensu-flow"}}
: ${MANAGED_RESOURCES:=${INPUT_MANAGED_RESOURCES:="checks,handlers,filters,mutators,assets,secrets/v1.Secret,roles,role-bindings,core/v2.HookConfig"}}
: ${NAMESPACES_DIR:=${INPUT_NAMESPACES_DIR:=".sensu/namespaces"}}
: ${NAMESPACES_FILE:=${INPUT_NAMESPACES_FILE:=".sensu/cluster/namespaces.yaml"}}
Expand Down Expand Up @@ -85,6 +86,13 @@ if [ $status -lt 200 ] || [ $status -ge 400 ]; then
echo "Probe of "$SENSU_BACKEND_URL/health" returned status code: $status"
exit 1
fi
if [[ $VERBOSE ]]; then echo "Checking Sensu auth credentials"; fi
status=$(curl --connect-timeout 30 -o /dev/null -s -w "%{http_code}" -X GET "${SENSU_BACKEND_URL}/auth/test" -u "${SENSU_USER}:${SENSU_PASSWORD}")
if [ $status -lt 200 ] || [ $status -ge 400 ]; then
echo "Sensu auth failed"
echo "Probe of "$SENSU_BACKEND_URL/auth/test" returned status code: $status"
exit 1
fi

if [ "$DISABLE_SANITY_CHECKS" = "false" ]; then
DISABLE_SANITY_CHECKS=""
Expand Down Expand Up @@ -175,7 +183,8 @@ function lint_resource_metadata {
if test -f ${NAMESPACES_FILE}
then
yq -N e '.' ${NAMESPACES_FILE} > /dev/null || die "$NAMESPACES_FILE is not valid yaml"

bad_resource_count=$(yq -N e '.type' ${NAMESPACES_FILE} | grep -c -v "Namespace")
if test $bad_resource_count -ne 0; then die "${NAMESPACES_FILE} has non Namespace Sensu Resources defined" ; fi
sensuctl create -f ${NAMESPACES_FILE} || die "sensuctl error creating namespaces file"

fi
Expand Down

0 comments on commit e15e6e3

Please sign in to comment.