mirror of
https://github.com/moghtech/komodo.git
synced 2026-05-05 15:34:09 -05:00
update docs. Add Variables / Secrets docs
This commit is contained in:
mbecker20
@@ -1,29 +1,57 @@
|
||||
# Permissioning Resources
|
||||
# Permissioning
|
||||
|
||||
All Komodo resources (servers, builds, deployment) have independant permission tables to allow for users to have granular access to these resources. By default, users do not see any resources until they are given at least read permissions.
|
||||
|
||||
## Permission Levels
|
||||
|
||||
There are 4 levels of permissions a user can have on a resource:
|
||||
|
||||
1. **None**. This is the lowest permission level, and means the user will not have any access to this resource. They will not see it in the GUI, and it will not show up if the user queries the core API directly. All attempts to view or update the resource will be blocked.
|
||||
|
||||
2. **Read**. This is the first permission level that grants any access. It will enable the user to see the resource in the GUI, read the configuration, and see any logs. Any attempts to update configuration or trigger any action will be blocked.
|
||||
|
||||
3. **Execute**. This level will allow the user to execute actions on the resource, like send a build command or trigger a redeploy. The user will still be blocked from updating configuration on the resource.
|
||||
|
||||
4. **Write**. The user has full access to the resource, they can execute any actions, update the configuration, and delete the resource.
|
||||
Komodo has a granular, layer-based permissioning system to provide non-admin users access only to intended Resources.
|
||||
|
||||
## User Groups
|
||||
|
||||
In addition to assigning permissions to users directly, admins can create User Groups and **assign permissions to them**, as if they were a user.
|
||||
Users can then be **added to multiple User Groups** and they **inherit the group's permissions**.
|
||||
While Komodo can assign permissions to specific users directly, it is recommended to instead **create User Groups and assign permissions to them**, as if they were a user.
|
||||
|
||||
Users can then be **added to multiple User Groups** and they **inherit the group's permissions**, similar to linux permissions.
|
||||
|
||||
For permissioning at scale, users can define [**User Groups in Resource Syncs**](/docs/sync-resources#user-group).
|
||||
|
||||
## Permission Levels
|
||||
|
||||
There are 4 permission levels a user / group can be given on a Resource:
|
||||
|
||||
1. **None**. The user will not have any access to the resource. The user **will not see it in the GUI, and it will not show up if the user queries the Komodo API directly**. All attempts to view or update the resource will be blocked. This is the default for non-admins, unless using `KOMODO_TRANSPARENT_MODE=true`.
|
||||
|
||||
2. **Read**. This is the first permission level that grants any access. It will enable the user to **see the resource in the GUI, read the configuration, and see any logs**. Any attempts to update configuration or trigger any action **will be blocked**. Using `KOMODO_TRANSPARENT_MODE=true` will make this level the base level on all resources, for all users.
|
||||
|
||||
3. **Execute**. This level will allow the user to execute actions on the resource, **like send a build command** or **trigger a redeploy**. The user will still be blocked from updating configuration on the resource.
|
||||
|
||||
4. **Write**. The user has full access to the resource, **they can execute any actions, update the configuration, and delete the resource**.
|
||||
|
||||
## Global permissions
|
||||
|
||||
Users or User Groups can be given a base permission level on all Resources of a particular type, such as Stack.
|
||||
In TOML form, this looks like:
|
||||
|
||||
```toml
|
||||
[[user_group]]
|
||||
name = "groupo"
|
||||
users = ["mbecker20", "karamvirsingh98"]
|
||||
all.Build = "Execute" # <- Group members can run all builds (but not update config),
|
||||
all.Stack = "Read" # <- And see all Stacks / logs (not deploy / update).
|
||||
```
|
||||
|
||||
A user / group can still be given a greater permission level on select resources:
|
||||
|
||||
```toml
|
||||
permissions = [
|
||||
{ target.type = "Stack", target.id = "my-stack", level = "Execute" },
|
||||
# Use regex to match multiple resources, for example give john execute on all of their Stacks
|
||||
{ target.type = "Stack", target.id = "\\^john-(.+)$\\", level = "Execute" },
|
||||
]
|
||||
```
|
||||
|
||||
## Administration
|
||||
|
||||
Users can be given admin priviledges by accessing the Komodo MongoDB and setting ```admin: true``` on the intended user document. These users have unrestricted access to all Komodo resources, like servers, builds, and deployments. Additionally, only these users can update other (non-admin) user's permissions on resources, an action not available to regular users even with **Update** level permissions.
|
||||
Users can be given Admin priviledges by a `Super Admin` (only the first user is given this status, set with `super_admin: true` on a User document in database). Super admins will see the "Make Admin" button when on a User page `/users/${user_id}`.
|
||||
|
||||
Komodo admins are responsible for managing user accounts as well. When a user logs into Komodo for the first time, they will not immediately be granted access. An admin must first **enable** the user, which can be done from the 'manage users' page (found in the user dropdown menu in the topbar). Users can also be **disabled** by an admin at any time, which blocks all their access to the GUI and API.
|
||||
These users have unrestricted access to all Komodo Resources. Additionally, these users can update other (non-admin) user's permissions on resources.
|
||||
|
||||
Komodo admins are responsible for managing user accounts as well. When a user logs into Komodo for the first time, they will not immediately be granted access (this can changed with `KOMODO_ENABLE_NEW_USERS=true`). An admin must first **enable** the user, which can be done from the `Users` tab on `Settings` page. Users can also be **disabled** by an admin at any time, which blocks all their access to the GUI and API.
|
||||
|
||||
Users also have some configurable global permissions, these are:
|
||||
|
||||
|
||||
@@ -12,54 +12,62 @@ All resources which depend on git repos / docker registries are able to use thes
|
||||
|
||||
## Server
|
||||
|
||||
-- Configure the connection to periphery agents.<br></br>
|
||||
-- Set alerting thresholds.<br></br>
|
||||
-- Can be attached to **Deployments**, **Stacks**, **Repos**, and **Builders**.
|
||||
- Configure the connection to periphery agents.
|
||||
- Set alerting thresholds.
|
||||
- Can be attached to by **Deployments**, **Stacks**, **Repos**, and **Builders**.
|
||||
|
||||
## Deployment
|
||||
|
||||
-- Deploy a docker container on the attached Server.<br></br>
|
||||
-- Manage services at the container level, perform orchestration using **Procedures** and **ResourceSyncs**.
|
||||
- Deploy a docker container on the attached Server.
|
||||
- Manage services at the container level, perform orchestration using **Procedures** and **ResourceSyncs**.
|
||||
|
||||
## Stack
|
||||
|
||||
-- Deploy with docker compose.<br></br>
|
||||
-- Provide the compose file in UI, or move the files to a git repo and use a webhook for auto redeploy on push.<br></br>
|
||||
-- Supports composing multiple compose files using `docker compose -f ... -f ...`.<br></br>
|
||||
-- Pass environment variables usable within the compose file. Interpolate in app-wide variables / secrets.
|
||||
- Deploy with docker compose.
|
||||
- Provide the compose file in UI, or move the files to a git repo and use a webhook for auto redeploy on push.
|
||||
- Supports composing multiple compose files using `docker compose -f ... -f ...`.
|
||||
- Pass environment variables usable within the compose file. Interpolate in app-wide variables / secrets.
|
||||
|
||||
## Repo
|
||||
|
||||
-- Put scripts in git repos, and run them on a Server, or using a Builder.<br></br>
|
||||
-- Can build binaries, perform automation, really whatever you can think of.
|
||||
- Put scripts in git repos, and run them on a Server, or using a Builder.
|
||||
- Can build binaries, perform automation, really whatever you can think of.
|
||||
|
||||
## Build
|
||||
|
||||
-- Build application source into docker images, and push them to the configured registry.<br></br>
|
||||
-- The source can be any git repo containing a Dockerfile.
|
||||
- Build application source into docker images, and push them to the configured registry.
|
||||
- The source can be any git repo containing a Dockerfile.
|
||||
|
||||
## Builder
|
||||
|
||||
-- Either points to a connected server, or holds configuration to launch a single-use AWS instance to build the image.<br></br>
|
||||
-- Can be attached to **Builds** and **Repos**.
|
||||
- Either points to a connected server, or holds configuration to launch a single-use AWS instance to build the image.
|
||||
- Can be attached to **Builds** and **Repos**.
|
||||
|
||||
## Procedure
|
||||
|
||||
-- Compose many actions on other resource type, like `RunBuild` or `DeployStack`, and run it on button push (or with a webhook).<br></br>
|
||||
-- Can run one or more actions in parallel "stages", and compose a series of parallel stages to run sequentially.
|
||||
- Compose many actions on other resource type, like `RunBuild` or `DeployStack`, and run it on button push (or with a webhook).
|
||||
- Can run one or more actions in parallel "stages", and compose a series of parallel stages to run sequentially.
|
||||
|
||||
## Action
|
||||
|
||||
- Write scripts calling the Komodo API in Typescript
|
||||
- Use a pre-initialized Komodo client within the script, no api keys necessary.
|
||||
- Type aware in UI editor. Get suggestions and see in depth docs as you type.
|
||||
- The Typescript client is also [published on NPM](https://www.npmjs.com/package/komodo_client).
|
||||
|
||||
## ResourceSync
|
||||
|
||||
-- Orchestrate all your configuration declaratively by defining it in `toml` files, which are checked into a git repo.<br></br>
|
||||
-- Can deploy **Deployments** and **Stacks** if changes are suggested.<br></br>
|
||||
-- Specify deploy ordering with `after` array. (like docker compose `depends_on` but can span across servers.).
|
||||
- Orchestrate all your configuration declaratively by defining it in `toml` files, which are checked into a git repo.
|
||||
- Can deploy **Deployments** and **Stacks** if changes are suggested.
|
||||
- Specify deploy ordering with `after` array. (like docker compose `depends_on` but can span across servers.).
|
||||
|
||||
## Alerter
|
||||
|
||||
-- Route alerts to various endpoints.<br></br>
|
||||
-- Can configure rules on each Alerter, such as resource whitelist, blacklist, or alert type filter.
|
||||
- Route alerts to various endpoints.
|
||||
- Can configure rules on each Alerter, such as resource whitelist, blacklist, or alert type filter.
|
||||
|
||||
## ServerTemplate
|
||||
|
||||
-- Easily expand your cloud network by storing cloud server lauch templates on various providers.<br></br>
|
||||
-- Auto connect the server to Komodo on launch, using `User Data` launch scripts.
|
||||
- Easily expand your cloud network by storing cloud server lauch templates on various providers.
|
||||
- Auto connect the server to Komodo on launch, using `User Data` launch scripts.
|
||||
- Currently supports **AWS EC2** and **Hetzner**
|
||||
|
||||
45
docsite/docs/variables.md
Normal file
45
docsite/docs/variables.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# Variables and Secrets
|
||||
|
||||
A variable / secret in Komodo is just a key-value pair.
|
||||
|
||||
```
|
||||
KEY_1 = "value_1"
|
||||
```
|
||||
|
||||
You can interpolate the value into any Environment (and most other user configurable inputs, such as Repo `On Clone` and `On Pull`, or Stack `Extra Args`) using double brackets around the key to trigger interpolation:
|
||||
|
||||
```toml
|
||||
# Before interpolation
|
||||
SOME_ENV_VAR = [[KEY_1]] # <- wrap the key in double brackets '[[]]'
|
||||
|
||||
# After iterpolation:
|
||||
SOME_ENV_VAR = value_1
|
||||
```
|
||||
|
||||
## Defining Variables and Secrets
|
||||
|
||||
- **In the UI**, you can go to `Settings` page, `Variables` tab. Here, you can create some Variables to store in the Komodo database.
|
||||
- There is a "secret" option you can check, this will **prevent the value from exposure in any updates / logs**, as well as prevent access to the value to any **non-admin** Komodo users.
|
||||
- Variables can also be managed in ResourceSyncs (see [example](/docs/sync-resources#deployments)) but should only be done for non-secret variables, to avoid committing sensitive data. You should manage secrets using one of the following options.
|
||||
|
||||
- **Mount a config file to Core**: https://komo.do/docs/setup/advanced#mount-a-config-file
|
||||
- In the Komodo Core config file, you can configure `secrets` using a block like:
|
||||
```toml
|
||||
# in core.config.toml
|
||||
[secrets]
|
||||
KEY_1 = "value_1"
|
||||
KEY_2 = "value_2"
|
||||
```
|
||||
- `KEY_1` and `KEY_2` will be available for interpolation on all your resources, as if they were Variables set up in the UI.
|
||||
- They keys are queryable and show up on the variable page (so you know they are available for use),
|
||||
but **the values are not exposed by API for ANY user**.
|
||||
|
||||
- **Mount a config file to Periphery agent**:
|
||||
|
||||
- In the Komodo Periphery config file, you can also configure `secrets` using the same syntax as the Core config file.
|
||||
- The variable **WILL NOT be available globally to all Komodo resources**, it will only be available to the resources on the associated Server resource on which that single Periphery agent is running.
|
||||
- This effectively distributes your secret locations, can be good or bad depending on your security requirements. It does avoid the need to send the secret over network from Core to Periphery, Periphery based secrets are never exposed to the network.
|
||||
|
||||
- **Use a dedicated secret management tool** such as Hashicorp Vault, alongside Komodo
|
||||
- Ultimately Komodo variable / secret features **may not fill enterprise level secret management requirements**, organizations of this level should use still a dedicated secret management solution. At this point Komodo is not intended as an enterprise level secret management solution.
|
||||
- These solutions do require application level integrations, your applications should only receive credentials to access the secret management API. **Your applications will pull the actual secret values from the dedicated secret management tool, they stay out of Komodo entirely**.
|
||||
@@ -1,15 +1,37 @@
|
||||
# Configuring Webhooks
|
||||
|
||||
Multiple Komodo resources can take advantage of webhooks from your git provider. Komodo supports incoming webhooks using the Github standard, which is also supported by other providers like Gitea.
|
||||
Multiple Komodo resources can take advantage of webhooks from your git provider. Komodo supports incoming webhooks using either the Github or Gitlab webhook authentication type, which is also supported by other providers like Gitea.
|
||||
|
||||
:::note
|
||||
On Gitea, the default "Gitea" webhook type works with the Github standard 👍
|
||||
On Gitea, the default "Gitea" webhook type works with the Github authentication type 👍
|
||||
:::
|
||||
|
||||
## Copy the Resource Payload URL
|
||||
## Copy the Webhook URL
|
||||
|
||||
Find the resource in UI, like a `Build`, `Repo`, or `Stack`.
|
||||
Scroll down to the bottom of Configuration area, and copy the webhook for the action you want.
|
||||
Go to the `Config` section, find "Webhooks", and copy the webhook for the action you want.
|
||||
|
||||
The webhook URL is constructed as follows:
|
||||
|
||||
```shell
|
||||
https://${HOST}/listener/${AUTH_TYPE}/${RESOURCE_TYPE}/${ID_OR_NAME}/${EXECUTION}
|
||||
```
|
||||
- **`HOST`**: Your Komodo endpoint to recieve webhooks.
|
||||
- If your Komodo sits in a private network,
|
||||
you will need a public proxy setup to forward `/listener` requests to Komodo.
|
||||
- **`AUTH_TYPE`**:
|
||||
- options: `github` | `gitlab`
|
||||
- `github`: Validates the signature attached with `X-Hub-Signature-256`. [reference](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)
|
||||
- `gitlab`: Checks that the secret attached to `X-Gitlab-Token` is valid. [reference](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html#create-a-webhook)
|
||||
- **`RESOURCE_TYPE`**:
|
||||
- options: `build` | `repo` | `stack` | `sync` | `procedure` | `action`
|
||||
- **`ID_OR_NAME`**:
|
||||
- Reference the specific resource by id or name. If the name may change, it is better to use id.
|
||||
- **`EXECUTION`**:
|
||||
- Which executions are available depends on the `RESOURCE_TYPE`. Builds only have the `/build` action.
|
||||
Repos can select between `/pull`, `/clone`, or `/build`. Stacks have `/deploy` and `/refresh`, and Resource Syncs have `/sync` and `/refresh`.
|
||||
- For **Procedures and Actions**, this will be the **branch to listen to for pushes**, or `__ALL__` to trigger
|
||||
on pushes to any branch.
|
||||
|
||||
## Create the webhook on the Git Provider
|
||||
|
||||
@@ -32,17 +54,4 @@ etc. only cares about a specific branch of the repo.
|
||||
|
||||
Because of this, the webhook will trigger the action **only on pushes to the branch configured on the resource**.
|
||||
|
||||
For example, if I make a build, I may point the build to the `release` branch of a particular repo. If I set up a webhook, and push to the `main` branch, the action will *not trigger*. It will only trigger when the push is to the `release` branch.
|
||||
|
||||
## Procedure webhooks
|
||||
|
||||
Not all actions support webhooks directly, however for those that don't, they can still be triggered via webhook by using a Procedure. Just create a Procedure and configure it to run the action you are looking for, and create a webhook pointing to the Procedure.
|
||||
|
||||
Since Procedures don't specificy a particular branch it should listen for pushes on, this information
|
||||
must be put in the webhook payload url. Procedures use webhook payload urls of the form:
|
||||
|
||||
```
|
||||
<KOMODO_HOST>/listener/github/procedure/<PROCEDURE_ID>/<LISTEN_BRANCH>
|
||||
```
|
||||
|
||||
If the `<LISTEN_BRANCH>` is not provided, it will default to listening on the `main` branch.
|
||||
For example, if I make a build, I may point the build to the `release` branch of a particular repo. If I set up a webhook, and push to the `main` branch, the action will *not trigger*. It will only trigger when the push is to the `release` branch.
|
||||
@@ -58,9 +58,10 @@ const sidebars: SidebarsConfig = {
|
||||
],
|
||||
},
|
||||
"docker-compose",
|
||||
"variables",
|
||||
"permissioning",
|
||||
"sync-resources",
|
||||
"webhooks",
|
||||
"permissioning",
|
||||
"version-upgrades",
|
||||
"api",
|
||||
"development"
|
||||
|
||||
Reference in New Issue
Block a user