|
1 | | - |
2 | | -> ⚠️ content deprecated, use https://docs.sysdig.com/en/docs/developer-tools/terraform-provider/ |
3 | | -
|
4 | | -# Terraform Provider for Sysdig |
5 | | - |
6 | | -## Introduction |
7 | | - |
8 | | -### What is Terraform |
9 | | - |
10 | | -[Terraform](https://www.terraform.io/) is a tool for building, changing, and versioning infrastructure safely and efficiently. |
11 | | -Terraform can manage existing and popular service providers as well as custom in-house solutions. |
12 | | - |
13 | | -Configuration files describe to Terraform the components needed to run a single application or |
14 | | -your entire datacenter. Terraform generates an execution plan describing what it will do to reach the |
15 | | -desired state, and then executes it to build the described infrastructure or configuration. |
16 | | - |
17 | | -As the configuration changes, Terraform is able to determine what changed and create incremental execution |
18 | | -plans which can be applied. |
19 | | - |
20 | | -### Terraform Provider for Sysdig |
21 | | - |
22 | | -The Terraform Provider for Sysdig allows you to manage your configuration in Sysdig Secure |
23 | | -and Sysdig Monitor as code, allowing you to synchronize your declarative configuration with |
24 | | -the configuration at the Platform. |
25 | | - |
26 | | -You can instrument several use cases like: |
27 | | -- Backup/restore |
28 | | -- Disaster recovery |
29 | | -- Configuration version management |
30 | | - |
31 | | -## Installation |
32 | | - |
33 | | -To use the provider, first you need to install Terraform, which is the main executable that |
34 | | -interacts with the provider. |
35 | | - |
36 | | -Download the Terraform executable for your OS/Architecture from |
37 | | -here: [https://www.terraform.io/downloads.html](https://www.terraform.io/downloads.html) |
38 | | - |
39 | | - |
40 | | -### Terraform v0.13+ |
41 | | - |
42 | | -As of Terraform 0.13, the new block `required_providers` was added, |
43 | | -making it easier to use community providers, since they are automatically |
44 | | -downloaded from the Terraform Registry. |
45 | | - |
46 | | -You can tell Terraform to download and use `sysdiglabs/sysdig` as the `sysdig` |
47 | | -provider by defining this block in one of your .tf files. |
48 | | - |
49 | | -```hcl |
50 | | -terraform { |
51 | | - required_providers { |
52 | | - sysdig = { |
53 | | - source = "sysdiglabs/sysdig" |
54 | | - version = ">= 0.4.0" |
55 | | - } |
56 | | - } |
57 | | -} |
58 | | -``` |
59 | | - |
60 | | -### Terraform v0.12 |
61 | | - |
62 | | -In older Terraform versions, you need to download the |
63 | | -[latest version of the Terraform Provider for Sysdig](https://github.com/sysdiglabs/terraform-provider-sysdig/releases/latest) |
64 | | -for your OS/Architecture, extract it and move the executable under `$HOME/.terraform.d/plugins` (you need to create |
65 | | -this directory if it does not exist yet) as this link suggests: |
66 | | -[https://www.terraform.io/docs/configuration/providers.html#third-party-plugins](https://www.terraform.io/docs/configuration/providers.html#third-party-plugins) . |
67 | | - |
68 | | -## Usage example |
69 | | - |
70 | | -Terraform will use the Sysdig provider when you specify a [resource](https://www.terraform.io/docs/configuration/resources.html) |
71 | | -or [data source](https://www.terraform.io/docs/configuration/data-sources.html) with a name starting with `sysdig_*` (i.e.: `sysdig_user`) |
72 | | - |
73 | | -But in order to actually create valid requests to the API and create/update/remove those resources, |
74 | | -you need to specify a correct API token for the product. |
75 | | - |
76 | | -You can do so in 2 ways: |
77 | | -1. Using environment variables |
78 | | -2. Using a tfvars file. |
79 | | - |
80 | | -### Configure the provider: Using env vars |
81 | | - |
82 | | -You can configure the following environment variables to specify the API token: |
83 | | -- `SYSDIG_SECURE_API_TOKEN` |
84 | | -- `SYSDIG_MONITOR_API_TOKEN` |
85 | | - |
86 | | -For example: |
87 | | - |
88 | | -```sh |
89 | | -$ export SYSDIG_SECURE_API_TOKEN=323232323-3232-3232-32323232 |
90 | | -$ export SYSDIG_MONITOR_API_TOKEN=343434343-3434-3434-34343434 |
91 | | -``` |
92 | | - |
93 | | -Once you execute Terraform and apply the manifests, that env vars will be used to configure |
94 | | -the provider and create API calls. |
95 | | - |
96 | | -### Configure the provider: Using a tfvars file |
97 | | - |
98 | | -To use a [tfvars file](https://www.terraform.io/docs/configuration/variables.html#variable-definitions-tfvars-files) |
99 | | -you need to first create it, and specify the API tokens as [variables](https://www.terraform.io/docs/configuration/variables.html), for example: |
100 | | - |
101 | | -``` |
102 | | -# File: terraform.tfvars |
103 | | -
|
104 | | -secure_token = "323232323-3232-3232-32323232" |
105 | | -monitor_token = "343434343-3434-3434-34343434" |
106 | | -``` |
107 | | - |
108 | | -Then, you can reference it in the [provider configuration block](https://www.terraform.io/docs/configuration/providers.html#provider-configuration): |
109 | | - |
110 | | -```hcl |
111 | | -provider "sysdig" { |
112 | | - sysdig_monitor_api_token = var.monitor_token |
113 | | - sysdig_secure_api_token = var.secure_token |
114 | | -} |
115 | | -``` |
116 | | - |
117 | | -### Creating resources with Terraform |
118 | | - |
119 | | -This is an example to create a pair of rules able to detect SSH connections and |
120 | | -shells spawned in containers. |
121 | | - |
122 | | -Start by defining a couple of rules in the `rules.tf` file. One rule will detect inbound and outbound connections |
123 | | -made to the port 22, and the other will detect a shell process being spawned. |
124 | | - |
125 | | -For more information about the configuration blocks, see: [https://www.terraform.io/docs/configuration/syntax.html](https://www.terraform.io/docs/configuration/syntax.html) |
126 | | - |
127 | | -```hcl |
128 | | -resource "sysdig_secure_rule_network" "disallowed_ssh_connection" { |
129 | | - name = "Disallowed SSH Connection detected" |
130 | | - description = "Detect any new ssh connection to a host" |
131 | | - tags = ["network"] |
132 | | -
|
133 | | - block_inbound = true |
134 | | - block_outbound = true |
135 | | -
|
136 | | - tcp { |
137 | | - matching = true |
138 | | - ports = [22] |
139 | | - } |
140 | | -} |
141 | | -
|
142 | | -resource "sysdig_secure_rule_process" "terminal_shell" { |
143 | | - name = "Terminal shell detected" |
144 | | - description = "A shell was used as the entrypoint/exec point" |
145 | | - tags = ["shell"] |
146 | | -
|
147 | | - processes = ["ash", "bash", "csh", "ksh", "sh", "tcsh", "zsh", "dash"] |
148 | | -} |
149 | | -``` |
150 | | - |
151 | | -Now create a policy in a file called `policy.tf` to define how these rules |
152 | | -are applied. The policy will stop the affected container and trigger a capture for |
153 | | -further troubleshooting. |
154 | | - |
155 | | -```hcl |
156 | | -resource "sysdig_secure_policy" "terminal_shell_or_ssh_in_container" { |
157 | | - name = "Terminal shell or SSH detected in container" |
158 | | - description = "Detects a terminal shell or a ssh spawned in a container" |
159 | | - enabled = true |
160 | | - severity = 0 // HIGH |
161 | | - scope = "container.id != \"\"" |
162 | | - rule_names = [sysdig_secure_rule_network.disallowed_ssh_connection.name, |
163 | | - sysdig_secure_rule_process.terminal_shell.name] |
164 | | -
|
165 | | - actions { |
166 | | - container = "stop" |
167 | | - capture { |
168 | | - seconds_before_event = 5 |
169 | | - seconds_after_event = 10 |
170 | | - } |
171 | | - } |
172 | | -} |
173 | | -``` |
174 | | - |
175 | | -With the given `scope`, the policy will only be applied to processes being executed inside containers: |
176 | | - |
177 | | -``` |
178 | | -scope = "container.id != \"\"" |
179 | | -``` |
180 | | - |
181 | | -Using `terraform apply` the resources are applied in the backend: |
182 | | - |
183 | | - |
184 | | - |
185 | | - Terraform tells us that is going to create 3 resources, which matches what we defined in `rules.tf` and `policy.tf`. |
186 | | - |
187 | | - |
188 | | - |
189 | | - After applying the plan, Terraform reports that the 3 resources have been successfully created. The policy uses the |
190 | | - rules created before, that’s why it’s the last one being created. |
191 | | - |
192 | | -The resources have been created, this is how they look in Sysdig Secure: |
193 | | - |
194 | | - |
195 | | - |
196 | | - |
197 | | - |
198 | | - But now the problem is that, if this policy triggers there's no alert notice unless notification channels are defined. |
199 | | -Creating two notification channels, one for the email and another one for slack in a file called `notification.tf`, |
200 | | -will alert us when the policy is triggered: |
201 | | - |
202 | | -```hcl |
203 | | -resource "sysdig_secure_notification_channel_email" "devops-email" { |
204 | | - name = "DevOps e-mail" |
205 | | - enabled = true |
206 | | - |
207 | | - notify_when_ok = false |
208 | | - notify_when_resolved = false |
209 | | -} |
210 | | -
|
211 | | -resource "sysdig_secure_notification_channel_slack" "devops-slack" { |
212 | | - name = "DevOps Slack" |
213 | | - enabled = true |
214 | | - url = "https://hooks.slack.com/services/xxxxxx/xxxxxxx/xxxxxxxxxxx" |
215 | | - channel = "#devops" |
216 | | - notify_when_ok = false |
217 | | - notify_when_resolved = false |
218 | | -} |
219 | | -``` |
220 | | - |
221 | | -Bind them to the policy, modifying the file `policy.tf`; note the `notification_channels` property: |
222 | | - |
223 | | -```hcl |
224 | | -resource "sysdig_secure_policy" "terminal_shell_or_ssh_in_container" { |
225 | | - name = "Terminal shell or SSH detected in container" |
226 | | - description = "Detects a terminal shell or a ssh spawned in a container" |
227 | | - enabled = true |
228 | | - severity = 0 // HIGH |
229 | | - scope = "container.id != \"\"" |
230 | | - rule_names = [sysdig_secure_rule_network.disallowed_ssh_connection.name, |
231 | | - sysdig_secure_rule_process.terminal_shell.name] |
232 | | -
|
233 | | - actions { |
234 | | - container = "stop" |
235 | | - capture { |
236 | | - seconds_before_event = 5 |
237 | | - seconds_after_event = 10 |
238 | | - } |
239 | | - } |
240 | | -
|
241 | | - notification_channels = [sysdig_secure_notification_channel_email.devops-email.id, |
242 | | - sysdig_secure_notification_channel_slack.devops-slack.id] |
243 | | -} |
244 | | -``` |
245 | | - |
246 | | -Finally, doing a `terraform apply`, it will inform that it will create 2 new resources and modify the existing policy: |
247 | | - |
248 | | - |
249 | | - |
250 | | - After inputting **yes**, Terraform will create the notification channels and bind them to the policy, |
251 | | - ensuring that the state in Monitor and Secure matches our state defined in the code. |
252 | | - |
253 | | -This is how the resources appear on the Sysdig Secure UI: |
254 | | - |
255 | | - |
256 | | - |
257 | | - |
258 | | - |
259 | | -Now, if someone tries to update it manually, by re-applying the policies, Terraform will |
260 | | -restore the desired status from the `.tf` manifests. |
261 | | - |
262 | | -## Full Terraform resources documentation |
263 | | - |
264 | | -Check all the available resources and datasources for the Terraform Provider for Sysdig here: |
265 | | - |
266 | | -[Terraform provider for Sysdig Datasources](https://registry.terraform.io/providers/sysdiglabs/sysdig/latest/docs) |
267 | | - |
268 | | ---- |
269 | | - |
| 1 | +> ⚠️ This documentation is deprecated and will be removed in a future version. |
| 2 | +> |
| 3 | +> Please refer to the [official documentation on the Terraform Registry](https://registry.terraform.io/providers/sysdiglabs/sysdig/latest/docs). |
0 commit comments