Skip to content

Commit 0b9a189

Browse files
alexazarhalexazarh
authored
Merge pull request #42 from QualiSystemsLab/feature/dan-docuementation
Feature/dan docuementation
2 parents c8b4bb5 + 604456b commit 0b9a189

3 files changed

Lines changed: 160 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 112 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,112 @@
1-
# CloudShell Terraform Shell
2-
TBD
1+
# CloudShell-Terraform-Shell
2+
Purpose: allow execution of Terraform deployment from CloudShell. Multiple Terraform services can be added to a Blueprint or Sandbox, and these can be executed from CloudShell Portal UI by the user that is reserving the Blueprint.
3+
4+
Additional workflow recommendation: it is very easy to customize Blueprint setup script that will run the “Execute Terraform” command on the service, and a similar teardown script that will run the “Destroy Terraform” command – this way the Terraform Module lifecycle is connected to the Sandbox lifecycle.
5+
6+
## Content
7+
* (1) cloudshell-iac-terraform - Python package that contains all the logic. It's assumed that this python package is used by a CloudShell Service
8+
* (2) generic_terraform_service - Main Shell
9+
* Used as is in a generic fashion or use it as an example to build an extension for a specific purpose (e.g. Azure MsSql, AWS RDS or any other managed cloud service)
10+
* (3) Remote backends
11+
* azure_tf_backend - Azure Remote Backend shell. See below for more details about usage
12+
13+
## Shell Usage Instructions
14+
15+
1. Import Shell(/s) to CloudShell “Shells” screen.
16+
2. Add Terraform Service to Blueprint/Sandbox.
17+
3. Configure the different attributes to match the requirement of the deployment. Please see below the documentation per attribute.
18+
19+
## Service Attributes (generic_terraform_service)
20+
|Attribute Name|Data Type|Description|Mandatory?|
21+
|:---|:---|:---|:---|
22+
|Github Terraform Module URL|String|Path to target module. Can be provided in three formats: <br/> 1) https://github.com/ACCOUNT/REPO/tree/BRANCH/PATH_TO_FOLDER <br/> 2) https://github.com/ACCOUNT/REPO/blob/BRANCH/PATH_TO_FOLDER/FILENAME.tf <br/> 3) https://raw.githubusercontent.com/ACCOUNT/REPO/BRANCH/PATH_TO_FOLDER/FILENAME.tf | Yes |
23+
|Terraform Version|String|The version of terraform.exe that will be downloaded and used (If not specified latest version will be used)| No |
24+
|Github Token|String| Github PAT (Private Access Token) to be used in order to download TF module. The entire repo will be downloaded and then the referenced TF module will be executed | Yes |
25+
|Cloud Provider|String| Reference to the CloudProvider resource that should be used to initialize the Terrafom provider. Supported cloud providers: <br> - Azure Shell <br>- Azure Shell 2G| Yes |
26+
|Branch|String| In case specified will override the branch in the Github Terraform Module URL | No |
27+
|Terraform Outputs|String| Unmapped and *non-sensitive* TF outputs will be stored as a CSV list of key value pairs on this attribute. This attribute is optional. | No |
28+
|Terraform Sensitive Outputs|Password| Unmapped and *sensitive* TF outputs will be stored as a CSV list of key value pairs on this attribute. This attribute must be of type "password. The attribute is optional. | No |
29+
|Terraform Inputs|String|CSV list of key value pairs to specify values for TF variables (e.g. varname1=varvalue1,varname2=varvalue2...)| No |
30+
|Remote State Provider|String|Reference a Remote State Provider resource to add a remote backend to your TF module. The remote backend definition will be added automatically to the TF module. Use this functionality to store the *tfstate* file in a secure location. <br/>If not specified, the *tf_state* file will be kept locally on the execution server in a temp directory and will be removed only after a successful destroy. This is considered less secure and should be used for development purposes only| No |
31+
|Apply Tags|Boolean|Specify whether TF resources will be auto-tagged. 6 default tags will be added automatically and also any custom tags will be added to all TF resources| N/A|
32+
|Custom Tags|String|Comma separated list of name=value pairs to be used as additional custom tags in case Apply Tags attribute is True| No |
33+
34+
### Attributes Auto Mapping
35+
36+
#### Auto mapping from attributes to TF Variables
37+
38+
Attributes that end with the postfix "_tfvar" will be automatically mapped to TF variables with the same name as the CloudShell attribute but without the postfix. <br>
39+
Example: <br>
40+
The value of a CloudShell attribute called "DB_Name_tfvar" will be automatically assigned to a TF variable called "DB_Name".
41+
42+
#### Auto mapping from TF Outputs to CloudShell attributes
43+
44+
Attributes that end with the postfix "_tfout" will be automatically updated with the value of TF Outputs that has the same name but without the postfix. <br>
45+
Example: <br>
46+
The value of a TF output "DB_Hostname" will be automatically set on an attribute with the name "DB_Hostname_tfout".
47+
48+
## Config Object (cloudshell-iac-terraform)
49+
The cloudshell-iac-terraform python package provides a configuration mechanism enabling you to set the behavior of the shell programmatically.
50+
The config object is 'TerraformShellConfig' and it has the following parameters:
51+
52+
|Attribute Name|Data Type|Default Value|Description|
53+
|:---|:---|:---|:---|
54+
| write_sandbox_messages | bool | False | When set to True will write info and error messages to the sandbox output |
55+
| update_live_status | bool | False | When set to True will update the livestatus icon for the CloudShell Service using the cloudshell-iac-terraform python package |
56+
| inputs_map | Dict | None | Defines a map between attribute names to TF variables. The value of the CloudShell attributes will be mapped to the TF variable |
57+
| outputs_map | Dict | None | Defines a map between TF outputs to CloudShell attributes. TF outputs will be saved as values on the mapped CloudShell attributes |
58+
59+
The "Generic Terraform Service" contains an example of how to use the config object.
60+
61+
## Commands (generic_terraform_service)
62+
|Command|Description|
63+
|:-----|:-----|
64+
|Execute Terraform| Takes care of the full deployment flow: Init, Plan and Apply.
65+
|Destroy Terraform|Destroys the Terraform deployment previously done for this module.|
66+
67+
## Remote Backends
68+
69+
Remote backend provider shells are used to apply remote backend functionality. If the "Remote State Provider"
70+
attribute is set with a name of a Remote Backend resource then the Terraform Shell will use this resource to get the
71+
information needed in order to inject the required configuration to set the TF module to use a remote backend.
72+
73+
It is strongly recommended to use this feature for security reasons.
74+
Terraform creates a state file called tfstate and it can contain sensitive data in plain text. When using a remote backend the tfstate file will be stored in remote storage and access to this storage should be controlled to prevent exposing sensitive data.
75+
76+
### Azure Remote Provider Shell (backends\azure_tf_backend)
77+
78+
The Azure Remote Provider shell is used in order to enable CloudShell access to Azure storage to be used in order to
79+
store the remote statefile.</br>
80+
One must create a resource and fill in the attributes - then specify that resource name as the Remote State Provider.
81+
Only one type of authentication is allowed either by Access Key or using the Cloud Provider authentication keys.
82+
83+
|Attribute|Type|Description|
84+
|:-----|:-----|:-----|
85+
Storage Account Name|String| The name of the Storage Account to be used |
86+
Container Name|String| The name of the Container to be used |
87+
Access Key|String| Access Key of the container|
88+
Cloud Provider|String| Cloud Provider resource name that holds the authentication keys|
89+
Resource Group|String| The resource group of the Storage Account|
90+
91+
### AWS Remote Provider Shell (backends\aws_tf_backend)
92+
Coming soon
93+
94+
\* Additional Remote Backend Providers are coming soon
95+
96+
## Additional Notes
97+
98+
* In order to avoid sensitive data showing up in the logs it's recommended to use Terraform version 0.14.0 or higher and set "sensitive = true" for all sensitive inputs and outputs.
99+
* The cloudshell-iac-terraform python package will create 2 log files. The first log file is the standard logging file used by all CloudShell shells. The second log file will contain the raw output from Terraform commands like "terraform plan" for example. The name of this log will start with "TF_EXEC_LOG_".
100+
* Unmapped sensitive outputs will be saved in an encrypted attribute ("password" type attribute) called "Terraform Sensitive Outputs" in case this attribute exists in shell-definition.yaml. Or ignored if the "Terraform Sensitive Outputs" doesn't exist.
101+
* When using the auto mapping feature with sensitive outputs/inputs it's the responsibility of the Shell developer to use attributes of type "password" to avoid exposing sensitive data.
102+
* All the shell commands are executed on an Execution Server using python’s “Sub Process” package. All the commands are executed with "shell=False" for increased security to avoid exposing sensitive data. And because "shell" is set to False, executions history will not be available in the Execution Server.
103+
104+
## Contributing
105+
106+
All your contributions are welcomed and encouraged. We've compiled detailed information about:
107+
108+
* [Contributing](contributing.md)
109+
110+
111+
## License
112+
[Apache License 2.0](https://github.com/QualiSystemslab/CloudShell-Terraform-Shell/blob/master/LICENSE)

‎contributing.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Contributing to CloudShell-Terraform-Shell
2+
We love your input! All your contributions are welcomed and encouraged. We want to make contributing to this project as easy and transparent as possible, whether it's:
3+
4+
- Reporting a bug
5+
- Discussing the current state of the code
6+
- Submitting a fix
7+
- Proposing new features
8+
- Becoming a maintainer
9+
10+
## We Develop with Github
11+
We use github to host code, to track issues and feature requests, as well as accept pull requests.
12+
13+
## We Use [Github Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests
14+
Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests:
15+
16+
1. Fork the repo and create your branch from `master`.
17+
2. If you've added code that should be tested, add tests.
18+
3. If you've changed APIs, update the documentation.
19+
4. Ensure the test suite passes.
20+
5. Make sure your code lints.
21+
6. Issue that pull request!
22+
23+
## Report bugs using Github's [issues](https://github.com/QualiSystemsLab/CloudShell-Terraform-Shell/issues)
24+
We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/QualiSystemsLab/CloudShell-Terraform-Shell/issues); it's that easy!
25+
26+
## Write bug reports with detail, background, and sample code
27+
28+
**Great Bug Reports** tend to have:
29+
30+
- A quick summary and/or background
31+
- Steps to reproduce
32+
- Be specific!
33+
- Give sample code if you can.
34+
- What you expected would happen
35+
- What actually happens
36+
- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
37+
38+
## Use a Consistent Coding Style
39+
40+
* Follow [PEP8](http://www.python.org/dev/peps/pep-0008/).
41+
* Include your name with TODOs as in # TODO(yourname). This makes it easier to find out who the author of the comment was.
42+
* Use only UNIX style newlines (\n), not Windows style (\r\n)
43+
44+
## License
45+
By contributing, you agree that your contributions will be licensed under its Apache-2.0 License.
46+
47+
## References
48+
This document was adapted from the open-source contribution guidelines for [Transcriptase](https://gist.github.com/briandk/3d2e8b3ec8daf5a27a62)

‎shells/generic_terraform_service/src/drivermetadata.xml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,7 @@
11
<Driver Description="Describe the purpose of your CloudShell shell" MainClass="driver.GenericTerraformServiceDriver"
22
Name="GenericTerraformServiceDriver" Version="1.0.0" PythonVersion="3">
33
<Layout>
4-
<Command Description="Deploy Terraform module." Name="run_terraform" DisplayName="Deploy Terraform"/>
54
<Command Description="Execute Terraform module." Name="execute_terraform" DisplayName="Execute Terraform"/>
65
<Command Description="Destroy Terraform module." Name="destroy_terraform" DisplayName="Destroy Terraform"/>
7-
<Command Description="Plan Terraform deployment." Name="plan_terraform" DisplayName="Plan Terraform"/>
8-
<Command Description="Get Terraform state." Name="show_terraform_state" DisplayName="Show Terraform State"/>
96
</Layout>
107
</Driver>

0 commit comments

Comments
 (0)