# Terraform Provider for Commander
## About
**Terraform Provider for Commander** lets you manage Keeper Security enterprise and MSP configuration as infrastructure-as-code. The provider uses the **Keeper Commander Service Mode REST API** to manage your Keeper resources from Terraform, so you get declarative config, version control, and a clear audit trail while staying on Keeper’s zero-knowledge infrastructure.
## Features
* **Resources:** Create and manage your Keeper resources from Terraform.
* **Import:** Most resources support **import state** so you can bring existing keeper resources under Terraform management with `terraform import` .
* **Data sources:** Read the existing resource data via data sources.
* **MSP support:** Use the optional `managed_company` attribute on enterprise resources and data sources to scope operations to a specific managed company.
## Available resources and data sources
> Full resources and data sources documentation on the [Terraform Registry](https://registry.terraform.io/providers/Keeper-Security/commander/latest/docs).
#### Resources
| Name | Description |
| --------------------------- | ---------------------------------------------------------------------------- |
| `commander_enterprise_node` | Create and manage enterprise nodes (MSP or enterprise account). |
| `commander_enterprise_role` | Create and manage enterprise roles and policies (MSP or enterprise account). |
| `commander_enterprise_team` | Create and manage enterprise teams (MSP or enterprise account). |
| `commander_enterprise_user` | Create and manage enterprise users (MSP or enterprise account). |
| `commander_managed_company` | Create and manage managed companies (MSP only). |
#### Data sources
| Name | Description |
| --------------------------- | ---------------------------------------------------------------------- |
| `commander_enterprise_node` | Look up an enterprise node by name or ID (MSP or enterprise account). |
| `commander_enterprise_role` | Look up an enterprise role by name or ID (MSP or enterprise account). |
| `commander_enterprise_team` | Look up an enterprise team by name or ID (MSP or enterprise account). |
| `commander_enterprise_user` | Look up an enterprise user by email or ID (MSP or enterprise account). |
| `commander_managed_company` | Look up a managed company by name or ID (MSP only). |
## Prerequisites
* **Keeper Commander Service Mode**: A service account running Commander Service Mode REST API.
* [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0
## Setup and Installation
In order to communicate between the Terraform and Keeper, the customer is responsible for hosting a Keeper Commander Service Mode instance. This can be accomplished many ways depending on your IT requirements. Commander Service Mode can run as a foreground service on any machine, or it can be run in a Docker container locally or remotely on a server.
### **Step 1.** Commander Setup
Follow the setup steps documented in the [Commander Service Mode REST API](https://docs.keeper.io/en/keeperpam/commander-cli/service-mode-rest-api) section to install Keeper Commander and start the service. Commander Service Mode can run directly in the CLI, in the background on a local machine, on a remote server as a service, or under a Docker container. Using Docker is the recommended method.
**Note the following Important Items:**
1\) The Request Queue System (API v2) must be enabled, e.g. `-q=y`
2\) Make sure the following commands are in the list:
{% code overflow="wrap" %}
```
this-device,sync-down,switch-to-mc,switch-to-msp,msp-add,msp-down,msp-info,msp-remove,msp-update,enterprise-info,enterprise-node,enterprise-user,enterprise-role,enterprise-team,enterprise-down,enterprise-push,team-approve,record-add,record-update,rm,get,list,record-type-info
```
{% endcode %}
{% hint style="info" %}
If you encounter a **429 Too Many Requests** error due to rate limiting, you can configure rate-limit for your service mode using the `-rl` or `--ratelimit` flag.
This allows you to configure the allowed number of requests per endpoint per IP address, for example:
* `1000/minute`
* `100000/hour`
* `2000000/day`
Adjust these limits based on your expected traffic and system capacity.
{% endhint %}
After service creation, the API key will be displayed in the console output. Make sure to copy and store it securely. If you are using Docker, you can pull the API key from the logs with this command:
```
docker compose logs | grep -i "generated api key"
```
When the Commander service is up and running, you should be able to submit a curl request to the endpoint. For example:
```bash
curl -X POST 'https://localhost:8080/api/v2/executecommand-async' \
--header 'Content-Type: application/json' \
--header 'api-key: ' \
--data '{"command": "this-device"}'
```
If the tunnel is running and the API key is correct, you should get a response like this:
```json
{
"success": true,
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"message": "Request queued successfully..."
}
```
Now that the service is up and running, you can use Service Mode URL and API Key in provider configuration.
{% hint style="info" %}
Keep the Commander Service Mode running in order to stay connected
{% endhint %}
### **Step 2.** Provider Installation
#### **Registry install**
To install this provider, add the following code to your Terraform configuration and run `terraform init`
```tf
terraform {
required_providers {
commander = {
source = "keeper-security/commander"
}
}
}
provider "commander" {
# Configuration options
}
```
#### Manual Installation
Download the latest version of the Terraform Provider for your platform from our [GitHub release](https://github.com/Keeper-Security/terraform-provider-commander/releases) page and copy the archive to the corresponding Terraform plugin folder (*creating any missing folders in the path*). Initialise source with full provider URL: source = `"github.com/keeper-security/commander"`
{% tabs %}
{% tab title="Windows" %}
```bash
SETLOCAL EnableExtensions && ^
mkdir %APPDATA%\.terraform.d\plugins\github.com\keeper-security\commander && ^
cd %APPDATA%\.terraform.d\plugins\github.com\keeper-security\commander && ^
curl -SfLOJ [ADD RELEASE LINK HERE LATER]
```
{% endtab %}
{% tab title="Mac OS" %}
```bash
mkdir -p ~/.terraform.d/plugins/github.com/keeper-security/commander && \
cd ~/.terraform.d/plugins/github.com/keeper-security/commander && \
curl -SfLOJ [ADD RELEASE LINK HERE LATER]
```
{% endtab %}
{% tab title="Linux" %}
```bash
mkdir -p ~/.terraform.d/plugins/github.com/keeper-security/commander && \
cd ~/.terraform.d/plugins/github.com/keeper-security/commander && \
curl -SfLOJ [ADD RELEASE LINK HERE LATER]
```
{% endtab %}
{% endtabs %}
For help on manually installing Terraform Providers, please refer to the [official Terraform documentation](https://www.terraform.io/docs/configuration/providers.html#third-party-plugins).
## Usage
### Configure the Provider
The provider needs to be configured with commander service mode url and api key before it can be used.
```tf
terraform {
required_providers {
commander = {
source = "keeper-security/commander"
}
}
}
provider "commander" {
service_mode_url = "http://localhost:8080/api/v2/"
service_mode_api_key = "XXXXXXXXXXXXXX"
}
```
{% hint style="info" %}
**Note: Using managed companies (MSP accounts)**\
\
Many resources and data sources support an optional `managed_company` attribute. When your account is an MSP, set `managed_company` to a managed company name or ID to manage that resource inside that company. Omit it to work in the logged-in account context (MSP or enterprise account).
{% endhint %}
{% hint style="info" %}
**Note: MSP - Using both a managed company and your main account in the same config**\
\
If you use some resources or data sources with `managed_company` (operations run inside that company) and others without it (operations run in the logged-in account context), Terraform may run them in parallel. Commander processes requests one at a time in a queue, so an action can run in the wrong context and fail (e.g. "resource not found").\
\
**Fix:** Add dependencies between those resources or data sources (e.g. `depends_on` or referencing one from the other) so they are not executed in parallel.\
\
**Example:** Force ordering so the main-account resource runs after the managed-company one:
```hcl
# Runs in managed company "Acme"
resource "commander_enterprise_team" "mc_team" {
name = "MC Team"
node = "Root"
managed_company = "Acme"
}
# Runs in logged-in account; depends on mc_team so it doesn't run in parallel
resource "commander_enterprise_team" "main_team" {
name = "Main Team"
node = "Root"
# no managed_company = main account
depends_on = [commander_enterprise_team.mc_team]
}
```
{% endhint %}
### Examples
#### Manage Enterprise Team
Below example explain how you can manage your enterprise team with help of "commander\_enterprise\_team" resource.
Use this resource to create and manage teams in the MSP or Enterprise account
```tf
terraform {
required_providers {
commander = {
source = "keeper-security/commander"
}
}
}
provider "commander" {
service_mode_url = "http://localhost:8080/api/v2/"
service_mode_api_key = "XXXXXXXXXXXXXX"
}
resource "commander_enterprise_team" "example" {
name = "Backend Developers"
node = "Engineering"
users = ["alice@example.com", "bob@example.com"]
roles = ["Developer"]
restrict_record_edit = true
restrict_record_re_share = true
enable_privacy_screen = false
# Optional, MSP Account only
# managed_company = "Acme Corp"
}
```
#### Read Enterprise Team
Below example explain how you can read your existing enterprise team with help of "commander\_enterprise\_team" data source.
Use this data source to look up an enterprise team by name or ID. Returns the team's ID, name, users, and roles so you can reference them in other resources.
```tf
terraform {
required_providers {
commander = {
source = "keeper-security/commander"
}
}
}
provider "commander" {
service_mode_url = "http://localhost:8080/api/v2/"
service_mode_api_key = "XXXXXXXXXXXXXX"
}
data "commander_enterprise_team" "example" {
team = "Backend Developers"
# Optional, MSP only
# managed_company = "Acme Corp"
}
output "team_id" {
value = data.commander_enterprise_team.example.id
}
output "team_name" {
value = data.commander_enterprise_team.example.name
}
output "team_users" {
value = data.commander_enterprise_team.example.users
}
output "team_roles" {
value = data.commander_enterprise_team.example.roles
}
```
For more examples on different resources and data sources, check out the detailed provider documentation.
#### Release Schedule and Roadmap
This all new Terraform Provider for Commander has a roadmap of features planned. Below is the current high level plan of features we are implementing:
* Sharing Folders
* Share Records
* SCIM
* SCIM Push
* Record Types
* SSO Cloud Integrations
* Keeper Gateways
Please [open a Github Issue](https://github.com/Keeper-Security/terraform-provider-commander/issues) with any specific requirements that you have.