Skip to content

Commit ca9dacb

Browse files
niheconomoumniheconomoum
committed
docs(readme): initial commit
1 parent f5c4910 commit ca9dacb

1 file changed

Lines changed: 88 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# satosa-refarch-aws
2+
3+
A reference implementation of SATOSA on Amazon Web Services using CloudFormation, CodePipeline, and ECS
4+
5+
## Quick Start
6+
7+
1. Fork this repository or copy it to a supported Git hosting service.
8+
9+
2. Deploy [the CI/CD pipeline](.cloudformation/pipeline.yaml) using CloudFormation.
10+
11+
3. If using a third-party Git hosting service, manually connect it to CodePipeline.
12+
13+
4. The CI/CD pipeline will deploy SATOSA automatically.
14+
15+
## Design
16+
17+
[The first CloudFormation template](.cloudformation/pipeline.yaml) creates a continuous integration/continuous delivery (CI/CD) pipeline and connects it to a Git repository. Repository state changes trigger the pipeline. The pipeline builds a custom SATOSA container from the configuration stored in the repository and deploys it using a second CloudFormation template. The pipeline will keep the container up to date by rebuilding and redeploying it on a weekly basis even if there were no changes to the repository. Internally, the pipeline temporarily stores build artifacts in an S3 bucket. It uses CodeBuild to build the SATOSA container image on an Amazon Linux EC2 instance running in a private VPC, which uploads images to a private ECR repository. If the container image built successfully, the pipeline creates or updates a CloudFormation stack that hosts SATOSA in ECS via EC2 or Fargate (the default).
18+
19+
Because CloudFormation stack parameters are not stored securely, they must not be used to define secrets such as the SAML token signing key-pair. Instead, the pipeline manages keying material using AWS Certificate Manager, AWS Secrets Manager, or AWS Systems Manager Parameter Store. To customize this keying material, specify a certificate ARN at pipeline deployment time (for custom certificates) or overwrite the values of the secrets/parameters created by the pipeline (for custom SAML key-pairs).
20+
21+
[The second CloudFormation template](.cloudformation/service.yaml) performs a [blue/green deployment](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-codedeploybluegreen.html) of a SATOSA container image stored in the CI/CD pipeline's private ECR repository.
22+
23+
## Removal
24+
25+
Always delete the service stack before deleting the pipeline stack.
26+
27+
If the stacks are deleted out of order, the pipeline stack deletion may deadlock on the ACM certificate deletion, as the certificate created by the pipeline stack will still be in use by the service stack. Furthermore, the service stack cannot be deleted in this state because the IAM role used to deploy it will no longer exist. To work around this issue, create a temporary IAM role that trusts the CloudFormation service and has [the AdministratorAccess policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html) attached. Update the service stack using the current template, changing the Image URI parameter to `satosa:latest`, the ECR Private Repository ARN parameter to the empty string, and the stack IAM role to the temporary IAM role. The update will fail but the IAM role change will persist, after which point the service stack may be deleted. Once the service stack deletion completes, the pipeline stack deletion will continue (or may be retried). Remove the temporary IAM role when finished.
28+
29+
After deleting the service stack, the following resources will remain:
30+
31+
- CloudWatch log groups for the ECS cluster, ALB instance, and VPC flow logs (if a VPC was reated)
32+
33+
After deleting the pipeline stack, the following resources will remain:
34+
35+
- an S3 bucket containing artifacts for each pipeline phase
36+
37+
- an ECR private repository storing Docker container images
38+
39+
- CloudWatch log groups for the CodeBuild project and VPC flow logs
40+
41+
These resources must be deleted manually if desired or (in some cases) if redeploying the stacks with the same names.
42+
43+
## Developer Notes
44+
45+
To deploy or update the service manually, use the latest successful build artifact.
46+
47+
```sh
48+
echo -n 'Pipeline stack name? '; read PIPELINE
49+
TEMP_DIR=$(mktemp -d)
50+
cd "${TEMP_DIR}"
51+
STACK_NAME=$(aws cloudformation describe-stacks --stack-name ${PIPELINE} --query 'Stacks[-1].Parameters[?contains(ParameterKey, `StackName`)].ParameterValue' --output text)
52+
ARTIFACT_BUCKET=$(aws cloudformation describe-stacks --stack-name ${PIPELINE} --query 'Stacks[-1].Outputs[?OutputKey==`ArtifactBucket`].OutputValue' --output text)
53+
LATEST_BUILD_ARTIFACT=$(aws s3api list-objects --bucket $ARTIFACT_BUCKET --query 'Contents[?contains(Key, `BuildArtif`)] | sort_by(@,& LastModified)[-1].Key' --output text)
54+
(aws s3api get-object --bucket ${ARTIFACT_BUCKET} --key ${LATEST_BUILD_ARTIFACT} /dev/stderr 3>&2 2>&1 1>&3) | bsdtar -x
55+
CFN_ACTION_ROLE_ARN=$(aws cloudformation describe-stacks --stack-name ${PIPELINE} --query 'Stacks[-1].Outputs[?OutputKey==`CloudFormationActionRoleArn`].OutputValue' --output text)
56+
aws cloudformation deploy --template-file service.yaml --stack-name ${STACK_NAME} --parameter-overrides file://config.json --capabilities CAPABILITY_IAM --role-arn ${CFN_ACTION_ROLE_ARN}
57+
```
58+
59+
To export the initial SATOSA configuration without using a volume mount, pipe a base64-encoded tar file to the host.
60+
61+
```sh
62+
docker run -it --rm satosa bash -c \
63+
'source docker-entrypoint.sh; docker_setup_env; docker_create_config > /dev/null 2>&1; rm *.crt *.key; tar cf - . | openssl base64' \
64+
| openssl base64 -d | tar xf -
65+
```
66+
67+
## Coding Style
68+
69+
Please follow [the Python Style Guide (PEP8)](https://pep8.org/), [Dockerfile best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/), [AWS CloudFormation best practices](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/best-practices.html), and [the Home Assistant YAML style guide](https://developers.home-assistant.io/docs/documenting/yaml-style-guide/) as appropriate.
70+
71+
In CloudFormation templates, please follow [the recommended template section ordering](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html#template-anatomy-sections).
72+
73+
In shell scripts, indent using single tabs instead of spaces.
74+
75+
## Git Commit Messages
76+
77+
Please follow [Angular Commit Message Conventions](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format). The following scopes are currently in use:
78+
- **pipeline**: the CloudFormation stack template defining the CI/CD pipeline
79+
- **service**: the CloudFormation stack template defining the service
80+
- **buildspec**: the CodeBuild specification
81+
- **config**: the service stack configuration template
82+
- **generate-key-pair-secret**: a CodeBuild project helper script
83+
- **dockerfile**: the container image definition, including [Dockerfile](Dockerfile)
84+
- **git**: Git repository configuration or GitHub-specific files; includes [.gitignore](.gitignore), [.gitattributes](.gitattributes), and [the GitHub Actions workflows](.github/workflows)
85+
- **proxy_conf**, **saml2_backend**, **saml2_frontend**, etc.: SATOSA/plugin configuration
86+
- **static_content**: a custom SATOSA front end used to serve metadata files
87+
- **license**: software licensing information, specificaly [LICENSE.md](LICENSE.md)
88+
- **readme**: this file

0 commit comments

Comments
 (0)