Skip to content

Commit d15f59e

Browse files
arm4barm4b
authored
Merge pull request #45 from bitovi/enh/readme
Various README enhancements
2 parents 4753cf3 + d81d5c7 commit d15f59e

File tree

1 file changed

+64
-55
lines changed

1 file changed

+64
-55
lines changed

‎README.md‎

Lines changed: 64 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,117 +1,126 @@
1-
# Deploy StackStorm
1+
# Github Action: Deploy StackStorm (βeta)
22

3-
GitHub action to deploy [StackStorm](https://stackstorm.com/) to an AWS VM (EC2).
3+
[![LICENSE](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
4+
[![Latest Release](https://img.shields.io/github/v/release/bitovi/github-actions-deploy-stackstorm)](https://github.com/bitovi/github-actions-deploy-stackstorm/releases)
5+
![GitHub closed issues](https://img.shields.io/github/issues-closed/bitovi/github-actions-deploy-stackstorm)
6+
![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/bitovi/github-actions-deploy-stackstorm)
7+
[![Join our Slack](https://img.shields.io/badge/slack-join%20chat-611f69.svg?logo=slack)](https://www.bitovi.com/community/slack?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
8+
9+
10+
GitHub action to deploy [StackStorm](https://stackstorm.com/) to an AWS VM (EC2) with [Terraform](operations/deployment/terraform/modules) and [Ansible](https://github.com/stackstorm/ansible-st2).
411

512
## Prerequisites
613
- An [AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) and [Access Keys](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html)
714
- The following secrets should be added to your GitHub actions secrets:
8-
- AWS_ACCESS_KEY_ID
9-
- AWS_SECRET_ACCESS_KEY
10-
- ST2_AUTH_USERNAME
11-
- ST2_AUTH_PASSWORD
15+
- `AWS_ACCESS_KEY_ID`
16+
- `AWS_SECRET_ACCESS_KEY`
17+
- `ST2_AUTH_USERNAME`
18+
- `ST2_AUTH_PASSWORD`
1219

1320

1421
## Example usage
1522

16-
Create `.github/workflow/deploy.yaml` with the following to build on push.
23+
Create a Github Action Workflow `.github/workflow/deploy-st2.yaml` with the following to build on push to the `main` branch.
1724

1825
```yaml
19-
name: Deploy ST2 Single VM with GHA
26+
# Deploy ST2 Single VM with GHA
27+
name: CD
2028

2129
on:
2230
push:
2331
branches: [ main ]
2432

25-
2633
jobs:
27-
deploy:
34+
deploy-st2:
2835
runs-on: ubuntu-latest
2936
steps:
30-
- id: deploy
31-
name: Deploy
37+
- id: deploy-st2
38+
name: Deploy StackStorm
39+
# NOTE: we recommend pinning to the latest numeric version
40+
# See: https://github.com/bitovi/github-actions-deploy-stackstorm/releases
3241
uses: bitovi/github-actions-deploy-stackstorm@main
3342
with:
43+
aws_default_region: us-east-1
3444
aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID}}
3545
aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}
36-
aws_default_region: us-east-1
3746
st2_auth_username: ${{ secrets.ST2_AUTH_USERNAME}}
3847
st2_auth_password: ${{ secrets.ST2_AUTH_PASSWORD}}
3948
```
4049
4150
This will create the following resources in AWS:
4251
- An EC2 instance
52+
- Route53 records
4353
- A load balancer
44-
- Security groups
45-
- Optionally, a VPC with subnets
54+
- Security groups (ports `80`, `443`, `22`)
55+
- Optionally, a VPC with subnets (see `aws_create_vpc`)
4656

47-
> For more details about what is created, see `operations/deployment/terraform/modules`
57+
> For more details about what is created, see [operations/deployment/terraform/modules](operations/deployment/terraform/modules/)
4858

4959
## Customizing
5060

5161
### Inputs
5262

53-
The following inputs can be used as `step.with` keys
63+
The following inputs can be used as `steps.with` keys:
5464

5565
| Name | Type | Default | Description |
5666
|------------------|---------|-------------|------------------------------------|
57-
| `checkout` | Bool | true | Specifies if this action should checkout the code (i.e. whether or not to run the `uses: actions/checkout@v3` action prior to deploying so that the deployment has access to the repo files) |
58-
| `aws_access_key_id` | String | | AWS access key ID (Required) |
59-
| `aws_secret_access_key` | String | | AWS secret access key (Required) |
60-
| `aws_session_token` | String | | AWS session token |
61-
| `aws_default_region` | String | us-east-1 | AWS default region (Required) |
62-
| `tf_state_bucket` | String | `${org}-${repo}-{branch}-tf-state` | AWS S3 bucket to use for Terraform state. |
63-
| `tf_state_bucket_destroy` | Bool | false | Force purge and deletion of tf_state_bucket defined. Any file contained there will be destroyed. `stack_destroy` must also be `true` |
64-
| `ec2_instance_profile` | String | | The AWS IAM instance profile to use for the EC2 instance |
65-
| `ec2_instance_type` | String | t2.medium | The AWS EC2 instance type. |
66-
| `stack_destroy` | Bool | false | Set to "true" to Destroy the stack |
67-
| `aws_resource_identifier` | String | `${org}-{repo}-{branch}` | Set to override the AWS resource identifier for the deployment. Use with destroy to destroy specific resources. |
68-
| `aws_create_vpc` | Bool | false | Whether an AWS VPC should be created in the action. |
69-
| `st2_auth_username` | String | | Username used by StackStorm standalone authentication |
70-
| `st2_auth_password` | String | | Password used by StackStorm standalone authentication |
71-
| `st2_packs` | String |`"st2"` | Comma separated list of packs to install. This flag does not work with a --python3 only pack.. If you modify this option, be sure to also include `st2` in the list. |
72-
| `infrastructure_only` | Bool | false | Does infrastructure (i.e. terraform) but **not** the deployment (i.e. ansible) |
73-
74-
75-
## Note about resource identifiers
76-
77-
Most resources will contain the tag GITHUB_ORG-GITHUB_REPO-GITHUB_BRANCH, some of them, even the resource name after.
78-
We limit this to a 60 characters string because some AWS resources have a length limit and short it if needed.
79-
80-
We use the kubernetes style for this. For example, kubernetes -> k(# of characters)s -> k8s. And so you might see some compressions are made.
81-
82-
For some specific resources, we have a 32 characters limit. If the identifier length exceeds this number after compression, we remove the middle part and replace it for a hash made up from the string itself.
67+
| `checkout` | bool | `true` | Specifies if this action should checkout the code (i.e. whether or not to run the `uses: actions/checkout@v3` action prior to deploying so that the deployment has access to the repo files) |
68+
| **AWS configuration** |
69+
| `aws_access_key_id` | string | | AWS access key ID (Required) |
70+
| `aws_secret_access_key` | string | | AWS secret access key (Required) |
71+
| `aws_session_token` | string | | AWS session token |
72+
| `aws_default_region` | string | `us-east-1` | AWS default region (Required) |
73+
| `ec2_instance_type` | string | `t2.medium` | The AWS EC2 instance type. |
74+
| `ec2_instance_profile` | string | | [The AWS IAM instance profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) to use for the EC2 instance. Use if you want to pass an AWS role with specific permissions granted to the instance |
75+
| `aws_resource_identifier` | string | `${org}-{repo}-{branch}` | Auto-generated by default so it's unique for org/repo/branch. Set to override with custom naming the unique AWS resource identifier for the deployment. |
76+
| `aws_create_vpc` | bool | `false` | Whether an AWS VPC should be created in the action. Otherwise, the existing default VPC will be used. |
77+
| `infrastructure_only` | bool | `false` | Does infrastructure (i.e. terraform) but **not** the deployment (i.e. ansible) |
78+
| **Teraform configuration** |
79+
| `tf_state_bucket` | string | `${org}-${repo}-{branch}-tf-state` | AWS S3 bucket to use for Terraform state. By default, a new deployment will be created for each unique branch. Hardcode if you want to keep a shared resource state between the several branches. |
80+
| **StackStorm configuration** |
81+
| `st2_auth_username` | string | | Username used by StackStorm standalone authentication. Set as a secret in GH Actions. |
82+
| `st2_auth_password` | string | | Password used by StackStorm standalone authentication. Set as a secret in GH Actions. |
83+
| `st2_packs` | string |`"st2"` | Comma separated list of packs to install. If you modify this option, be sure to also include `st2` in the list. |
84+
| **Cleanup** |
85+
| `stack_destroy` | bool | `false` | Set to `true` to Destroy the created AWS infrastructure for this instance |
86+
| `tf_state_bucket_destroy` | bool | `false` | Force purge and deletion of `tf_state_bucket` defined. Any file contained there will be destroyed. `stack_destroy` must also be `true`. Use if you want to clean up the resources |
87+
88+
89+
## Note about AWS resource identifiers
90+
Most resources will contain the tag `GITHUB_ORG-GITHUB_REPO-GITHUB_BRANCH` to make them unique. Because some AWS resources have a length limit, we shorten identifiers to a `60` characters max string.
91+
92+
We use the Kubernetes style for this. For example, `Kubernetes` -> `k(# of characters)s` -> `k8s`. And so you might see how compressions are made.
93+
94+
For some specific resources, we have a `32` characters limit. If the identifier length exceeds this number after compression, we remove the middle part and replace it with a hash made up of the string itself.
8395

8496
### S3 buckets naming
85-
86-
Buckets name can be made of up to 63 characters. If the length allows us to add `-tf-state`, we will do so. If not, a simple `-tf` will be added.
97+
Bucket names can be made of up to 63 characters. If the length allows us to add `-tf-state`, we will do so. If not, a simple `-tf` will be added.
8798

8899
## Made with BitOps
89-
[BitOps](https://bitops.sh) allows you to define Infrastructure-as-Code for multiple tools in a central place. This action uses a BitOps [Operations Repository](https://bitops.sh/operations-repo-structure/) to set up the necessary Terraform and Ansible to create infrastructure and deploy to it.
100+
[BitOps](https://bitops.sh/) allows you to define Infrastructure-as-Code for multiple tools in a central place. This action uses BitOps [Operations Repository Structure](https://bitops.sh/operations-repo-structure/) to organize the necessary Terraform and Ansible steps, create infrastructure and deploy to it.
90101

91102
## Future
92-
In the future, this action will support more cloud providers (via [BitOps Plugins](https://bitops.sh/plugins/) like [AWS](https://github.com/bitops-plugins/aws)) such as
103+
In the future, this action may support more cloud providers (via [BitOps Plugins](https://bitops.sh/plugins/) like [AWS](https://github.com/bitops-plugins/aws)) such as:
93104
- [Google Cloud Platform](https://cloud.google.com/gcp)
94105
- [Microsoft Azure](https://azure.microsoft.com/en-us/)
95106
- [Nutanix](https://www.nutanix.com/)
96107
- [Open Stack](https://www.openstack.org/)
97108
- [VMWare](https://www.vmware.com/)
98109
- etc
99110

100-
This action will also support multiple deployment types such as:
111+
This action may also support multiple deployment types such as:
101112
- [Kubernetes](https://github.com/StackStorm/stackstorm-k8s)
102113
- Multi-VM
103114

104-
## Contributing
105-
We would love for you to contribute to [bitovi/github-actions-deploy-docker-to-ec2](https://github.com/bitovi/github-actions-deploy-docker-to-ec2). [Issues](https://github.com/bitovi/github-actions-deploy-docker-to-ec2/issues) and [Pull Requests](https://github.com/bitovi/github-actions-deploy-docker-to-ec2/pulls) are welcome!
115+
This action is still in its early stages, so we welcome your feedback! [Open an issue](issues/) if you have a feature request.
106116

107-
## License
108-
The scripts and documentation in this project are released under the [MIT License](https://github.com/bitovi/github-actions-deploy-docker-to-ec2/blob/main/LICENSE).
117+
## Contributing
118+
We would love for you to contribute to [bitovi/github-actions-deploy-stackstorm](/). [Issues](issues/) and [Pull Requests](pulls/) are welcome!
109119

110120
## Provided by Bitovi
111121
[Bitovi](https://www.bitovi.com/) is a proud supporter of Open Source software.
112122

113-
114123
## Need help?
115-
Bitovi has consultants that can help. Drop into [Bitovi's Community Slack](https://www.bitovi.com/community/slack), and talk to us in the `#devops` channel!
124+
Bitovi has consultants that can help. Drop into [Bitovi's Community Slack](https://www.bitovi.com/community/slack), and talk to us in the `#devops` channel!
116125

117-
Need DevOps Consulting Services? Head over to https://www.bitovi.com/devops-consulting, and book a free consultation.
126+
Need DevOps Consulting Services? Head over to https://www.bitovi.com/devops-consulting, and book a free consultation.

0 commit comments

Comments
 (0)