diff --git a/app/docs/src/explanation/aws-authentication.md b/app/docs/src/explanation/aws-authentication.md index 92484f2d62..353b8e0bd5 100644 --- a/app/docs/src/explanation/aws-authentication.md +++ b/app/docs/src/explanation/aws-authentication.md @@ -11,13 +11,13 @@ System Initiative provides a number of ways to authenticate to AWS. If you have generated static access keys for a user then you can set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` directly in the `AWS Credential` -asset. +Asset. ## AWS SSO Credentials If you have generated credentials via the command `aws sso login` then you can set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` -directly in the `AWS Credential` asset. +directly in the `AWS Credential` Asset. ## Assuming a Role @@ -28,7 +28,7 @@ nothing except assume roles in other accounts. The ARN of the user is Every workspace has a unique token assigned to it at creation. It is accessible from within your workspace via the gear icon in the upper right. Please treat -this as a secret. +this as a Secret. You can create a role using the token and the arn above, with a trust relationship as below and attach any required permissions you want to give the @@ -55,6 +55,6 @@ role: ``` Take the arn of the role that you created and set that in the `AssumeRole` field -in the AWS Credential asset. You don’t need to set an access key or a secret -access key. You can ensure it works by putting an AWS Credential on the asset, -selecting the secret you created and it will validate your credentials. +in the AWS Credential Asset. You don’t need to set an access key or a secret +access key. You can ensure it works by putting an AWS Credential on the Asset, +selecting the Secret you created and it will validate your credentials. diff --git a/app/docs/src/how-tos/aws-ecr-ecs.md b/app/docs/src/how-tos/aws-ecr-ecs.md index e5a944bc48..8fa64b0f46 100644 --- a/app/docs/src/how-tos/aws-ecr-ecs.md +++ b/app/docs/src/how-tos/aws-ecr-ecs.md @@ -31,24 +31,24 @@ We will cover: All activities in this how-to happen within an AWS Region and AWS Credential. -Start in a change set named `ECR Infrastructure How-to`. +Start in a Change Set named `ECR Infrastructure How-to`. ## Walkthrough ### What it will look like -When you are through with this guide, you should have components that look like -this in your diagram: +When you are through with this guide, you should have Components that look like +this in your Diagram: ![AWS ECS Diagram](./aws-ecr-ecs/complete.png) ### Create AWS Credentials -Add a `AWS Credential` to your change set and configure your AWS credentials +Add a `AWS Credential` to your Change Set and configure your AWS credentials ### Select an AWS Region -Add a `AWS Region` to your change set and set the `region` property to +Add a `AWS Region` to your Change Set and set the `region` property to `us-east-1`. ### Create an ECR Repository @@ -57,9 +57,9 @@ Add a `AWS Region` to your change set and set the `region` property to Add an `ECR Private Repository` to your `us-east-1` region frame. -Set the component name to be `demo-app-repo policy`. +Set the Component name to be `demo-app-repo policy`. -Set the component type to be `Configuration Frame (down)`. +Set the Component type to be `Configuration Frame (down)`. Set the `repositoryName` to be `demo-app-repo`. @@ -71,9 +71,9 @@ Set `ForceDelete` to be `true`. Add an `ECR Repository Policy` to your `demo-app-repo` repository frame. -Set the component name to be `demo-app-repo policy` +Set the Component name to be `demo-app-repo policy` -Set the component type to be `Configuration Frame (up)`. +Set the Component type to be `Configuration Frame (up)`. ### Create an IAM Condition Operator @@ -81,7 +81,7 @@ Set the component type to be `Configuration Frame (up)`. Add an `IAM Condition Operator` to the `demo-app-repo policy` frame. -Set component name to be `ECSAllow Tag`. +Set Component name to be `ECSAllow Tag`. Set the `ConditionKey` to be `aws:PrincipalTag/ECSAccess` @@ -99,7 +99,7 @@ Set the value to be `True`. Add an `IAM Policy Statement` to the `demo-app-repo policy` frame. -Set the component name to be `AllowPullForECSTasks` +Set the Component name to be `AllowPullForECSTasks` Set the `Sid` to be `AllowPullForECSTasks` @@ -119,8 +119,8 @@ Set the values to be: - `ecr:BatchGetImage` - `ecr:BatchCheckLayerAvailability` -Connect the `Condition` output socket of the `ECSAllow Tag` component to the -`Condition` input socket of this `AllowPullForECSTasks` component. +Connect the `Condition` Output Socket of the `ECSAllow Tag` Component to the +`Condition` Input Socket of this `AllowPullForECSTasks` Component. ### Apply your ECR Infrastructure Change Set @@ -145,7 +145,7 @@ Firstly, `docker pull` this container locally: docker pull infrastructureascode/hello-world ``` -Go to the `Resource` tab of the `demo-app-repo` component and select +Go to the `Resource` tab of the `demo-app-repo` Component and select `Resource Data`. This data includes the `repositoryUri`. Next, `docker tag` the image for the ECR container created: @@ -173,19 +173,19 @@ Lastly, `docker push` the image: docker push 'repositoryUri':latest ``` -### Create a new Change set +### Create a new Change Set -Create a new change set called `ECS Infra`. +Create a new Change Set called `ECS Infra`. -### Create a Loadbalancer component +### Create a Loadbalancer Component ![Create Loadbalancer](./aws-ecr-ecs/create-loadbalancer.png) Add a `Loadbalancer` to your `VPC How-to` vpc frame. -Set the component type to be `Configuration Frame (down)`. +Set the Component type to be `Configuration Frame (down)`. -Set the component name to `application-alb`. +Set the Component name to `application-alb`. Set the `LbName` to `application-alb`. @@ -195,31 +195,31 @@ Set the `LbType` to be `application`. Set the `Scheme` to be `internet-facing`. -Connect the `Subnet ID` output socket of each of the public subnet components to -the `Subnet ID` input socket of the `application-alb` component. +Connect the `Subnet ID` Output Socket of each of the public subnet Components to +the `Subnet ID` Input Socket of the `application-alb` Component. -### Create a Security Group component for the Loadbalancer +### Create a Security Group Component for the Loadbalancer ![Create Security Group](./aws-ecr-ecs/create-ec2-security-group.png) Add a `Security Group` to your `VPC How-to` vpc frame. -Set the component name to `alb-sg`. +Set the Component name to `alb-sg`. Set the `GroupName` to `alb-sg`. Set the `Description` to be `Security Group to allow access to the Loadbalancer` -Connect the `Security Group ID` output socket of `alb-sg` component to the -`Security Group ID` input socket of the `application-alb` frame. +Connect the `Security Group ID` Output Socket of `alb-sg` Component to the +`Security Group ID` Input Socket of the `application-alb` frame. -### Create an Ingress Rule component +### Create an Ingress Rule Component ![Create Ingress Rule](./aws-ecr-ecs/create-security-group-ingress.png) Add a `Security Group Rule (Ingress)` to your `VPC How-to` vpc frame. -Set the component name to be `alb-80-ingress`. +Set the Component name to be `alb-80-ingress`. Set the `Description` to be `Ingress to allow 80 from the world`. @@ -230,30 +230,30 @@ Add an `IpRange` array item. Set the `IP Range [CIDR]` to be `0.0.0.0/0` and the `Description` to be `The world`. -Connect the `Security Group ID` output socket of `alb-sg` component to the -`Security Group ID` input socket of this `alb-80-ingress` component. +Connect the `Security Group ID` Output Socket of `alb-sg` Component to the +`Security Group ID` Input Socket of this `alb-80-ingress` Component. -### Create a Listener component +### Create a Listener Components ![Create Listener](./aws-ecr-ecs/create-listener.png) -Add a `Listener` component to your `application-alb` loadbalancer frame. +Add a `Listener` Component to your `application-alb` loadbalancer frame. -Set the component name to `HTTP:80`. +Set the Component name to `HTTP:80`. Set the `Port` to be `80`. Set the `Protocol` to be `HTTP`. -Resize the frame to be large enough to fit another component. +Resize the frame to be large enough to fit another Component. ### Create a Target Group ![Create Target Group](./aws-ecr-ecs/create-target-group.png) -Add a `Target Group` component to your `Listener` frame. +Add a `Target Group` Component to your `Listener` frame. -Set the component name to `app-tg`. +Set the Component name to `app-tg`. Set `TgName` to be `app-tg`. @@ -281,16 +281,16 @@ Set `TargetType` to be `ip`. Set `UnhealthyThresholdCount` to be `2`. -Connect the `Target Group ARN` output socket of `app-tg` component to the -`Target Group ARN` input socket of the `HTTP:80` frame. +Connect the `Target Group ARN` Output Socket of `app-tg` Component to the +`Target Group ARN` Input Socket of the `HTTP:80` frame. ### Create an IAM Role ![Create IAM Role](./aws-ecr-ecs/create-iam-role.png) -Add an `AWS IAM Role` component to your `VPC How-to` vpc frame. +Add an `AWS IAM Role` Component to your `VPC How-to` vpc frame. -Set the component name to `ecs-tasks-service`. +Set the Component name to `ecs-tasks-service`. Set the `RoleName` to `ecs-tasks-service`. @@ -309,7 +309,7 @@ Set the `Value` to be `Allow` Add an `AWS IAM Policy Statement` within the `ecs-tasks-service` AWS IAM Role frame. -Set the component name to `ecs-tasks-assume-role-policy`. +Set the Component name to `ecs-tasks-assume-role-policy`. Set the `Effect` to `Allow`. @@ -323,36 +323,36 @@ Add an array item to the `Service` section. Set the value to be `ecs-tasks.amazonaws.com`. -### Create a Security Group component for the Application +### Create a Security Group Component for the Application ![create-security-group-for-application](./aws-ecr-ecs/create-security-group-for-application.png) Add a `Security Group` to your `VPC How-to` vpc frame. -Set the component name to `container-sg` +Set the Component name to `container-sg` Set the `GroupName` to `container-sg`. Set the `Description` to be `Container Security Group` -### Create an Ingress Rule component for the Application +### Create an Ingress Rule Component for the Application ![create-ingress-rule-for-application.png](./aws-ecr-ecs/create-ingress-rule-for-application.png) Add a `Security Group Rule (Ingress)` to your `VPC How-to` vpc frame. -Set the component name to be `container-8080-ingress`. +Set the Component name to be `container-8080-ingress`. Set the `Description` to be `Ingress to allow access to port 8080`. Set the `TrafficPort` to be `8080/tcp`. -Connect the `Security Group ID` output socket of `container-sg` component to the -`Security Group ID` input socket of this`container-80-ingress` component. +Connect the `Security Group ID` Output Socket of `container-sg` Component to the +`Security Group ID` Input Socket of this`container-80-ingress` Component. -Connect the `Security Group ID` output socket of `alb-sg` component to the -`Source Traffic Security Group ID` input socket of this `container-80-ingress` -component. +Connect the `Security Group ID` Output Socket of `alb-sg` Component to the +`Source Traffic Security Group ID` Input Socket of this `container-80-ingress` +Component. ### Create an ECS Cluster @@ -360,9 +360,9 @@ component. Add an `ECS Cluster` to your `VPC How-to` vpc frame. -Set the component type to be `Configuration Frame (down)`. +Set the Component type to be `Configuration Frame (down)`. -Set the component name to `application-cluster`. +Set the Component name to `application-cluster`. Set the `ClusterName` to `application-cluster`. @@ -374,7 +374,7 @@ Set the `Description` to be `Cluster to run the Tutorial App` Add an `ECS Service` to your `application-cluster` cluster frame. -Set the component name to `demo-service`. +Set the Component name to `demo-service`. Set the `serviceName` to `demo-service`. @@ -382,11 +382,11 @@ Set the `desiredCount` to be `1`. Set the `description` to be `Service to run my demo application`. -Connect the `Subnet ID` output socket of each of the private subnet components -to the `Subnet ID` input socket of this `demo-service` component. +Connect the `Subnet ID` Output Socket of each of the private subnet Components +to the `Subnet ID` Input Socket of this `demo-service` Component. -Connect the `Security Group ID` output socket of `container-sg` component to the -`Security Group ID` input socket of this `demo-service` component. +Connect the `Security Group ID` Output Socket of `container-sg` Component to the +`Security Group ID` Input Socket of this `demo-service` Component. ### Create an ECS Task Definition @@ -394,9 +394,9 @@ Connect the `Security Group ID` output socket of `container-sg` component to the Add an `ECS Task Definition` to your `demo-service` service frame. -Set the component type to be `Configuration Frame (up)`. +Set the Component type to be `Configuration Frame (up)`. -Set the component name to `demo-app`. +Set the Component name to `demo-app`. Set the `taskDefinitionFamily` to be `demo-app`. @@ -406,8 +406,8 @@ Set `memory` to be `.5 GB`. Set the `runtimePlatform` based on the architecture of the container image. -Connect the `ARN` output socket of the `ecs-tasks-service` AWS IAM Role to the -`Task Role ARN` input socket of your `demo-app` ECS Task Definition. +Connect the `ARN` Output Socket of the `ecs-tasks-service` AWS IAM Role to the +`Task Role ARN` Input Socket of your `demo-app` ECS Task Definition. ### Create a Container Definition @@ -415,14 +415,14 @@ Connect the `ARN` output socket of the `ecs-tasks-service` AWS IAM Role to the Add a `Container Definition` to your `demo-app` frame. -Set the component name to `hello-world`. +Set the Component name to `hello-world`. Set `Name` to `hello-world`. Set `Essential` to be selected. -Connect the `Repository Uri` output socket of the `demo-app-repo` to the -`Container Image` input socket of this `hello-world` container definition. +Connect the `Repository Uri` Output Socket of the `demo-app-repo` to the +`Container Image` Input Socket of this `hello-world` container definition. ### Create an ECS Container Definition Port Mapping @@ -430,7 +430,7 @@ Connect the `Repository Uri` output socket of the `demo-app-repo` to the Add a `ECS Container Definition Port Mapping` to the `demo-app` frame. -Set the component name to be `http`. +Set the Component name to be `http`. Set the `name` to be `http`. @@ -440,8 +440,8 @@ Set the `hostPort` to be `8080`. Set the `protocol` to be `tcp`. -Connect the `Port Mapping` output socket of this `http` ECS Container Defintion -Port Mapping to the `Port Mapping` input socket of the `hello-world` Container +Connect the `Port Mapping` Output Socket of this `http` ECS Container Defintion +Port Mapping to the `Port Mapping` Input Socket of the `hello-world` Container Defintion. ### Create a ECS Load Balancer Configuration @@ -450,16 +450,16 @@ Defintion. Add a `ECS Load Balancer Configuration` to the `demo-service` frame. -Set the component name to be `lb-config`. +Set the Component name to be `lb-config`. -Connect the `Target Group ARN` output socket of the `app-tg` Target Group to the -`Target Group ARN` input socket of this `lb-config` component. +Connect the `Target Group ARN` Output Socket of the `app-tg` Target Group to the +`Target Group ARN` Input Socket of this `lb-config` Component. -Connect the `Container Name` output socket of the `hello-world` Container -Defintion to the `Container Name` input socket of this `lb-config` component. +Connect the `Container Name` Output Socket of the `hello-world` Container +Defintion to the `Container Name` Input Socket of this `lb-config` Component. -Connect the `Container Port` output socket of the `http` ECS Container Defintion -Port Mapping to the `Container Port` input socket of this `lb-config` component. +Connect the `Container Port` Output Socket of the `http` ECS Container Defintion +Port Mapping to the `Container Port` Input Socket of this `lb-config` Component. ### Create an IAM Role Policy @@ -467,13 +467,13 @@ Port Mapping to the `Container Port` input socket of this `lb-config` component. Add a `IAM Role Policy` to the `How to VPC` frame. -Set the component name to be `ecs-tasks-service additional policy` +Set the Component name to be `ecs-tasks-service additional policy` Set the `PolicyArn` to be `arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy` -Connect the `RoleName` output socket of the `ecs-tasks-service` IAM Role to the -`RoleName` input socket of this `ecs-tasks-service additional policy` component. +Connect the `RoleName` Output Socket of the `ecs-tasks-service` IAM Role to the +`RoleName` Input Socket of this `ecs-tasks-service additional policy` Component. ### Apply your Change Set @@ -492,17 +492,21 @@ Click the `Apply Change Set` button to: Review the completed AWS resources by clicking the `Resource` sub-panel for each of your new resources. -Select the `application-alb` component on the model. Go to the `Resource Data` +Select the `application-alb` Component on the Model. Go to the `Resource Data` screen and you will find the `DNSName`. You can visit that URL in the browser and inspect the running application. ### Clean Up -Create a new change set called `Clean up How-to` +Create a new Change Set called `Clean up How-to` -Delete your `VPC How-to` VPC frame. All of the components inside will be marked +Delete your `VPC How-to` VPC frame. All of the Components inside will be marked for deletion. Click `Apply Change Set`. All your new resources should be deleted from your AWS account. + +## Vocabulary +In this guide bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/how-tos/aws-ecs.md b/app/docs/src/how-tos/aws-ecs.md index c8713c52e8..93128fa7f0 100644 --- a/app/docs/src/how-tos/aws-ecs.md +++ b/app/docs/src/how-tos/aws-ecs.md @@ -27,26 +27,26 @@ We will cover: All activities in this how-to happen within a configured VPC, AWS Region and AWS Credential. -Start in a change set named `ECS How-to`. +Start in a Change Set named `ECS How-to`. ## Walkthrough ### What it will look like -When you are through with this guide, you should have components that look like -this in your diagram: +When you are through with this guide, you should have Components that look like +this in your Diagram: ![AWS ECS Diagram](./aws-ecs/aws-ecs-complete.png) -### Create a Loadbalancer component +### Create a Loadbalancer Component ![Create Loadbalancer](./aws-ecs/create-loadbalancer.png) Add a `Loadbalancer` to your `VPC How-to` vpc frame. -Set the component type to be `Configuration Frame (down)`. +Set the Component type to be `Configuration Frame (down)`. -Set the component name to `application-alb`. +Set the Component name to `application-alb`. Set the `LbName` to `application-alb`. @@ -56,31 +56,31 @@ Set the `LbType` to be `application`. Set the `Scheme` to be `internet-facing`. -Connect the `Subnet ID` output socket of each of the public subnet components to -the `Subnet ID` input socket of the `application-alb` component. +Connect the `Subnet ID` Output Socket of each of the public subnet Components to +the `Subnet ID` Input Socket of the `application-alb` Component. -### Create a Security Group component for the Loadbalancer +### Create a Security Group Component for the Loadbalancer ![Create Security Group](./aws-ecs/create-ec2-security-group.png) Add a `Security Group` to your `VPC How-to` vpc frame. -Set the component name to `alb-sg`. +Set the Component name to `alb-sg`. Set the `GroupName` to `alb-sg`. Set the `Description` to be `Security Group to allow access to the Loadbalancer` -Connect the `Security Group ID` output socket of `alb-sg` component to the -`Security Group ID` input socket of the `application-alb` frame. +Connect the `Security Group ID` Output Socket of `alb-sg` Component to the +`Security Group ID` Input Socket of the `application-alb` frame. -### Create an Ingress Rule component +### Create an Ingress Rule Component ![Create Ingress Rule](./aws-ecs/create-security-group-ingress.png) Add a `Security Group Rule (Ingress)` to your `VPC How-to` vpc frame. -Set the component name to be `alb-80-ingress`. +Set the Component name to be `alb-80-ingress`. Set the `Description` to be `Ingress to allow 80 from the world`. @@ -91,30 +91,30 @@ Add an `IpRange` array item. Set the `IP Range [CIDR]` to be `0.0.0.0/0` and the `Description` to be `The world`. -Connect the `Security Group ID` output socket of `alb-sg` component to the -`Security Group ID` input socket of this `alb-80-ingress` component. +Connect the `Security Group ID` Output Socket of `alb-sg` Component to the +`Security Group ID` Input Socket of this `alb-80-ingress` Component. -### Create a Listener component +### Create a Listener Component ![Create Listener](./aws-ecs/create-listener.png) -Add a `Listener` component to your `application-alb` loadbalancer frame. +Add a `Listener` Component to your `application-alb` loadbalancer frame. -Set the component name to `HTTP:80`. +Set the Component name to `HTTP:80`. Set the `Port` to be `80`. Set the `Protocol` to be `HTTP`. -Resize the frame to be large enough to fit another component. +Resize the frame to be large enough to fit another Component. ### Create a Target Group ![Create Target Group](./aws-ecs/create-target-group.png) -Add a `Target Group` component to your `Listener` frame. +Add a `Target Group` Component to your `Listener` frame. -Set the component name to `app-tg`. +Set the Component name to `app-tg`. Set `TgName` to be `app-tg`. @@ -142,16 +142,16 @@ Set `TargetType` to be `ip`. Set `UnhealthyThresholdCount` to be `2`. -Connect the `Target Group ARN` output socket of `app-tg` component to the -`Target Group ARN` input socket of the `HTTP:80` frame. +Connect the `Target Group ARN` Output Socket of `app-tg` Component to the +`Target Group ARN` Input Socket of the `HTTP:80` frame. ### Create an IAM Role ![Create IAM Role](./aws-ecs/create-iam-role.png) -Add an `AWS IAM Role` component to your `VPC How-to` vpc frame. +Add an `AWS IAM Role` Component to your `VPC How-to` vpc frame. -Set the component name to `ecs-tasks-service`. +Set the Component name to `ecs-tasks-service`. Set the `RoleName` to `ecs-tasks-service`. @@ -166,7 +166,7 @@ Set the `Path` to `/si-tutorial/`. Add an `AWS IAM Policy Statement` within the `ecs-tasks-service` AWS IAM Role frame. -Set the component name to `ecs-tasks-assume-role-policy`. +Set the Component name to `ecs-tasks-assume-role-policy`. Set the `Effect` to `Allow`. @@ -181,44 +181,44 @@ Set the `[0]` value for the `Action` array to `sts:AssumeRole`. Add an `AWS IAM Service Principal` within the `ecs-tasks-service` AWS IAM Role frame. -Set the component name to `ecs-tasks.amazonaws.com`. +Set the Component name to `ecs-tasks.amazonaws.com`. Set the `Service` to `ecs-tasks.amazonaws.com`. -Connect the `Principal` output socket of the `ecs-tasks.amazonaws.com` AWS IAM -AWS Service Principal to the `Principal` input socket of your +Connect the `Principal` Output Socket of the `ecs-tasks.amazonaws.com` AWS IAM +AWS Service Principal to the `Principal` Input Socket of your `ecs-tasks-assume-role-policy` AWS IAM Policy Statement. -### Create a Security Group component for the Application +### Create a Security Group Component for the Application ![create-security-group-for-application](./aws-ecs/create-security-group-for-application.png) Add a `Security Group` to your `VPC How-to` vpc frame. -Set the component name to `container-sg` +Set the Component name to `container-sg` Set the `GroupName` to `container-sg`. Set the `Description` to be `Container Security Group` -### Create an Ingress Rule component for the Application +### Create an Ingress Rule Component for the Application ![create-ingress-rule-for-application.png](./aws-ecs/create-ingress-rule-for-application.png) Add a `Security Group Rule (Ingress)` to your `VPC How-to` vpc frame. -Set the component name to be `container-80-ingress`. +Set the Component name to be `container-80-ingress`. Set the `Description` to be `Ingress to allow access to port 80`. Set the `TrafficPort` to be `80/tcp`. -Connect the `Security Group ID` output socket of `container-sg` component to the -`Security Group ID` input socket of this`container-80-ingress` component. +Connect the `Security Group ID` Output Socket of `container-sg` Component to the +`Security Group ID` Input Socket of this`container-80-ingress` Component. -Connect the `Security Group ID` output socket of `alb-sg` component to the -`Source Traffic Security Group ID` input socket of this `container-80-ingress` -component. +Connect the `Security Group ID` Output Socket of `alb-sg` Component to the +`Source Traffic Security Group ID` Input Socket of this `container-80-ingress` +Component. ### Create an ECS Cluster @@ -226,9 +226,9 @@ component. Add an `ECS Cluster` to your `VPC How-to` vpc frame. -Set the component type to be `Configuration Frame (down)`. +Set the Component type to be `Configuration Frame (down)`. -Set the component name to `application-cluster`. +Set the Component name to `application-cluster`. Set the `ClusterName` to `application-cluster`. @@ -240,7 +240,7 @@ Set the `Description` to be `Cluster to run the Tutorial App` Add an `ECS Service` to your `application-cluster` cluster frame. -Set the component name to `demo-service`. +Set the Component name to `demo-service`. Set the `serviceName` to `demo-service`. @@ -248,11 +248,11 @@ Set the `desiredCount` to be `1`. Set the `description` to be `Service to run my demo application`. -Connect the `Subnet ID` output socket of each of the private subnet components -to the `Subnet ID` input socket of this `demo-service` component. +Connect the `Subnet ID` Output Socket of each of the private subnet Components +to the `Subnet ID` Input Socket of this `demo-service` Component. -Connect the `Security Group ID` output socket of `container-sg` component to the -`Security Group ID` input socket of this `demo-service` component. +Connect the `Security Group ID` Output Socket of `container-sg` Component to the +`Security Group ID` Input Socket of this `demo-service` Component. ### Create an ECS Task Definition @@ -260,9 +260,9 @@ Connect the `Security Group ID` output socket of `container-sg` component to the Add an `ECS Task Definition` to your `demo-service` service frame. -Set the component type to be `Configuration Frame (up)`. +Set the Component type to be `Configuration Frame (up)`. -Set the component name to `demo-app`. +Set the Component name to `demo-app`. Set the `taskDefinitionFamily` to be `demo-app`. @@ -270,8 +270,8 @@ Set `cpu` to be `0.25 vCPU`. Set `memory` to be `.5 GB`. -Connect the `ARN` output socket of the `ecs-tasks-service` AWS IAM Role to the -`Task Role ARN` input socket of your `demo-app` ECS Task Definition. +Connect the `ARN` Output Socket of the `ecs-tasks-service` AWS IAM Role to the +`Task Role ARN` Input Socket of your `demo-app` ECS Task Definition. ### Create a Container Definition @@ -279,7 +279,7 @@ Connect the `ARN` output socket of the `ecs-tasks-service` AWS IAM Role to the Add a `Container Definition` to your `demo-app` frame. -Set the component name to `hello-world`. +Set the Component name to `hello-world`. Set `Name` to `hello-world`. @@ -291,12 +291,12 @@ Set `Essential` to be selected. Add a `Docker Image` to your `demo-app` frame. -Set the component name to `tutum/hello-world`. +Set the Component name to `tutum/hello-world`. Set `image` to be `tutum/hello-world`. -Connect the `Container Image` output socket of this `tutum/hello-world` Docker -Image to the `Container Image` input socket of the `hello-world` Container +Connect the `Container Image` Output Socket of this `tutum/hello-world` Docker +Image to the `Container Image` Input Socket of the `hello-world` Container Defintion. ### Create an ECS Container Definition Port Mapping @@ -305,7 +305,7 @@ Defintion. Add a `ECS Container Definition Port Mapping` to the `demo-app` frame. -Set the component name to be `http`. +Set the Component name to be `http`. Set the `name` to be `http`. @@ -315,8 +315,8 @@ Set the `hostPort` to be `80`. Set the `protocol` to be `tcp`. -Connect the `Port Mapping` output socket of this `http` ECS Container Defintion -Port Mapping to the `Port Mapping` input socket of the `hello-world` Container +Connect the `Port Mapping` Output Socket of this `http` ECS Container Defintion +Port Mapping to the `Port Mapping` Input Socket of the `hello-world` Container Defintion. ### Create a ECS Load Balancer Configuration @@ -325,16 +325,16 @@ Defintion. Add a `ECS Load Balancer Configuration` to the `demo-service` frame. -Set the component name to be `lb-config`. +Set the Component name to be `lb-config`. -Connect the `Target Group ARN` output socket of the `app-tg` Target Group to the -`Target Group ARN` input socket of this `lb-config` component. +Connect the `Target Group ARN` Output Socket of the `app-tg` Target Group to the +`Target Group ARN` Input Socket of this `lb-config` Component. -Connect the `Container Name` output socket of the `hello-world` Container -Defintion to the `Container Name` input socket of this `lb-config` component. +Connect the `Container Name` Output Socket of the `hello-world` Container +Defintion to the `Container Name` Input Socket of this `lb-config` Component. -Connect the `Container Port` output socket of the `http` ECS Container Defintion -Port Mapping to the `Container Port` input socket of this `lb-config` component. +Connect the `Container Port` Output Socket of the `http` ECS Container Defintion +Port Mapping to the `Container Port` Input Socket of this `lb-config` Component. ### Apply your Change Set @@ -357,11 +357,15 @@ of your new resources. ### Clean Up -Create a new change set called `Clean up How-to` +Create a new Change Set called `Clean up How-to` -Delete your `VPC How-to` VPC frame. All of the components inside will be marked +Delete your `VPC How-to` VPC frame. All of the Components inside will be marked for deletion. Click `Apply Change Set`. All your new resources should be deleted from your AWS account. + +## Vocabulary +In this guide bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/how-tos/aws-eks.md b/app/docs/src/how-tos/aws-eks.md index b5f1aecde9..866bb7e814 100644 --- a/app/docs/src/how-tos/aws-eks.md +++ b/app/docs/src/how-tos/aws-eks.md @@ -27,24 +27,24 @@ We will cover: All activities in this how-to happen within a configured VPC, AWS Region, and AWS Credential. -Start in a change set named `EKS How-to`. +Start in a Change Set named `EKS How-to`. ## Walkthrough ### What it will look like -When you are through with this guide, you should have components that look like -this in your diagram: +When you are through with this guide, you should have Components that look like +this in your Diagram: ![AWS EKS Diagram](./aws-eks/complete.png) -### Create an EKS cluster component +### Create an EKS cluster Component ![Create Security Group](./aws-eks/create-eks-cluster.png) Add an `EKS Cluster` to your `VPC How-to` vpc frame. -Set the component name to `demo-eks-cluster`. +Set the Component name to `demo-eks-cluster`. Set the `name` to `demo-eks-cluster`. @@ -56,31 +56,31 @@ Set the value of that array item to `api`. Set `resourcesVpcConfig.endpointPublicAccess` to be `true`. -Connect the `Subnet ID` output socket of each of the private subnet components -to the `Subnet ID` input socket of this `demo-eks-cluster` component. +Connect the `Subnet ID` Output Socket of each of the private subnet Components +to the `Subnet ID` Input Socket of this `demo-eks-cluster` Component. -### Create a Security Group component for the Cluster +### Create a Security Group Component for the Cluster ![Create Security Group](./aws-eks/create-ec2-security-group.png) Add a `Security Group` to your `VPC How-to` vpc frame. -Set the component name to `eks-cluster-sg`. +Set the Component name to `eks-cluster-sg`. Set the `GroupName` to `eks-cluster-sg`. Set the `Description` to `Security Group to allow access to the EKS Cluster` -Connect the `Security Group ID` output socket of `eks-cluster-sg` component to -the `Security Group ID` input socket of the `demo-eks-cluster` frame. +Connect the `Security Group ID` Output Socket of `eks-cluster-sg` Component to +the `Security Group ID` Input Socket of the `demo-eks-cluster` frame. -### Create an Ingress Rule component +### Create an Ingress Rule Component ![Create Ingress Rule](./aws-eks/create-security-group-ingress.png) Add a `Security Group Rule (Ingress)` to your `VPC How-to` vpc frame. -Set the component name to `eks-cluster-443-ingress`. +Set the Component name to `eks-cluster-443-ingress`. Set the `Description` to `Ingress to allow 443 from the world`. @@ -91,24 +91,24 @@ Add an `IpRange` array item. Set the `IP Range [CIDR]` to `0.0.0.0/0` and the `Description` to `The world`. -Connect the `Security Group ID` output socket of `eks-cluster-sg` component to -the `Security Group ID` input socket of this `eks-cluster-443-ingress` -component. +Connect the `Security Group ID` Output Socket of `eks-cluster-sg` Component to +the `Security Group ID` Input Socket of this `eks-cluster-443-ingress` +Component. ### Create an IAM Role ![Create IAM Role](./aws-eks/create-iam-role.png) -Add an `AWS IAM Role` component to your `VPC How-to` vpc frame. +Add an `AWS IAM Role` Component to your `VPC How-to` vpc frame. -Set the component name to `eks-cluster-role`. +Set the Component name to `eks-cluster-role`. Set the `RoleName` to `eks-cluster-role`. Set the `Description` to `IAM Role for EKS Cluster`. -Connect the `ARN` output socket of the `eks-cluster-role` AWS IAM Role to the -`Role ARN` input socket of your `demo-eks-cluster` EKS Cluster. +Connect the `ARN` Output Socket of the `eks-cluster-role` AWS IAM Role to the +`Role ARN` Input Socket of your `demo-eks-cluster` EKS Cluster. ### Create an AWS IAM Policy Statement @@ -117,7 +117,7 @@ Connect the `ARN` output socket of the `eks-cluster-role` AWS IAM Role to the Add an `AWS IAM Policy Statement` within the `demo-eks-cluster-role` AWS IAM Role frame. -Set the component name to `eks-cluster-role-policy`. +Set the Component name to `eks-cluster-role-policy`. Set the `Effect` to `Allow`. @@ -130,17 +130,17 @@ Set the `[0]` value for the `Action` array to `sts:AssumeRole`. Add an `AWS IAM Service Principal` within the `demo-eks-cluster-role` AWS IAM Role frame. -Set the component name to `eks.amazonaws.com`. +Set the Component name to `eks.amazonaws.com`. Set the `Service` to `eks.amazonaws.com`. -Connect the `Principal` output socket of the `eks.amazonaws.com` AWS IAM AWS -Service Principal to the `Principal` input socket of your +Connect the `Principal` Output Socket of the `eks.amazonaws.com` AWS IAM AWS +Service Principal to the `Principal` Input Socket of your `eks-cluster-role-policy` AWS IAM Policy Statement. ### Connect Additional Access Policies to the IAM Role -Add 2 `Aws IAM Role Policy` components to the `demo-eks-cluster-role` AWS IAM +Add 2 `Aws IAM Role Policy` Components to the `demo-eks-cluster-role` AWS IAM Role frame. Configure them as follows: @@ -150,8 +150,8 @@ Configure them as follows: | AmazonEKSClusterPolicy | arn:aws:iam::aws:policy/AmazonEKSClusterPolicy | | AmazonEKSServicePolicy | arn:aws:iam::aws:policy/AmazonEKSServicePolicy | -Connect the `RoleName` output socket of the `demo-eks-cluster-role` to the -`RoleName` input socket of each of the AWS IAM Role Policy components in that +Connect the `RoleName` Output Socket of the `demo-eks-cluster-role` to the +`RoleName` Input Socket of each of the AWS IAM Role Policy Components in that frame. ### Create a Fargate Profile @@ -160,18 +160,18 @@ frame. Add a `Fargate Profile` to your `demo-eks-cluster` eks cluster frame. -Set the component type to `Up Frame`. +Set the Component type to `Up Frame`. -Set the component name to `demo-fargate-profile`. +Set the Component name to `demo-fargate-profile`. Set the `fargateProfileName` to `demo-fargate-profile`. -Connect the `Subnet ID` output socket of each of the private subnet components -to the `Subnet ID` input socket of this `demo-fargate-profile` component. +Connect the `Subnet ID` Output Socket of each of the private subnet Components +to the `Subnet ID` Input Socket of this `demo-fargate-profile` Component. -Add a `POD Profile Selector` component inside the `demo-fargate-profile` frame. +Add a `POD Profile Selector` Component inside the `demo-fargate-profile` frame. -Set the component name to `default namespace`. +Set the Component name to `default namespace`. Set the `namespace` to `default`. @@ -179,16 +179,16 @@ Set the `namespace` to `default`. ![Create IAM Role for Fargate Profile](./aws-eks/create-iam-role-for-fargate.png) -Add an `AWS IAM Role` component to your `VPC How-to` vpc frame. +Add an `AWS IAM Role` Component to your `VPC How-to` vpc frame. -Set the component name to `fargate-profile-role`. +Set the Component name to `fargate-profile-role`. Set the `RoleName` to `fargate-profile-role`. Set the `Description` to `IAM Role for EKS Cluster`. -Connect the `ARN` output socket of the `fargate-profile-role` AWS IAM Role to -the `Role ARN` input socket of your `demo-fargate-profile` Fargate Profile. +Connect the `ARN` Output Socket of the `fargate-profile-role` AWS IAM Role to +the `Role ARN` Input Socket of your `demo-fargate-profile` Fargate Profile. ### Create an AWS IAM Policy Statement @@ -197,7 +197,7 @@ the `Role ARN` input socket of your `demo-fargate-profile` Fargate Profile. Add an `AWS IAM Policy Statement` within the `fargate-profile-role` AWS IAM Role frame. -Set the component name to `fargate-profile-role-policy`. +Set the Component name to `fargate-profile-role-policy`. Set the `Effect` to `Allow`. @@ -210,17 +210,17 @@ Set the `[0]` value for the `Action` array to `sts:AssumeRole`. Add an `AWS IAM Service Principal` within the `fargate-profile-role` AWS IAM Role frame. -Set the component name to `eks-fargate-pods.amazonaws.com`. +Set the Component name to `eks-fargate-pods.amazonaws.com`. Set the `Service` to `eks-fargate-pods.amazonaws.com`. -Connect the `Principal` output socket of the `eks-fargate-pods.amazonaws.com` -AWS IAM AWS Service Principal to the `Principal` input socket of your +Connect the `Principal` Output Socket of the `eks-fargate-pods.amazonaws.com` +AWS IAM AWS Service Principal to the `Principal` Input Socket of your `fargate-profile-role-policy` AWS IAM Policy Statement. ### Connect Additional Access Policy to the IAM Role -Add an `Aws IAM Role Policy` component to the `fargate-profile-role` AWS IAM +Add an `Aws IAM Role Policy` Component to the `fargate-profile-role` AWS IAM Role frame. Configure it as follows: @@ -229,17 +229,17 @@ Configure it as follows: | -------------------------------------- | -------------------------------------------------------------- | | AmazonEKSFargatePodExecutionRolePolicy | arn:aws:iam::aws:policy/AmazonEKSFargatePodExecutionRolePolicy | -Connect the `RoleName` output socket of the `demo-eks-cluster-role` to the -`RoleName` input socket of each of the AWS IAM Role Policy components in that +Connect the `RoleName` Output Socket of the `demo-eks-cluster-role` to the +`RoleName` Input Socket of each of the AWS IAM Role Policy Components in that frame. -### Create a NodeGroup component +### Create a NodeGroup Component ![Create NodeGroup](./aws-eks/create-nodegroup.png) Add a `NodeGroup` to your `demo-eks-cluster` eks-cluster frame. -Set the component name to `demo-nodegroup`. +Set the Component name to `demo-nodegroup`. Set the `nodegroupName` to `demo-nodegroup`. @@ -255,34 +255,34 @@ Set the `scalingConfig.maxSize` to `3`. Set the `scalingConfig.minSize` to `1`. -Connect the `Subnet ID` output socket of each of the private subnet components -to the `Subnet ID` input socket of the `demo-nodegroup` component. +Connect the `Subnet ID` Output Socket of each of the private subnet Components +to the `Subnet ID` Input Socket of the `demo-nodegroup` Component. -### Create a Key Pair component +### Create a Key Pair Component ![Create Key Pair](./aws-eks/create-key-pair.png) Add a `Key Pair` to your `demo-eks-cluster` frame. -Set the component name to `demo-eks-nodegroup-key-pair`. +Set the Component name to `demo-eks-nodegroup-key-pair`. Set the `KeyName` to `demo-eks-nodegroup-key-pair`. -Connect the `Key Name` output socket of this `demo-eks-nodegroup-key-pair` -component to the `Key Name` input socket of the `demo-nodegroup` component. +Connect the `Key Name` Output Socket of this `demo-eks-nodegroup-key-pair` +Component to the `Key Name` Input Socket of the `demo-nodegroup` Component. ### Create an IAM Role for Node Group -Add an `AWS IAM Role` component to your `VPC How-to` vpc frame. +Add an `AWS IAM Role` Component to your `VPC How-to` vpc frame. -Set the component name to `nodegroup-profile-role`. +Set the Component name to `nodegroup-profile-role`. Set the `RoleName` to `nodegroup-profile-role`. Set the `Description` to `IAM Role for EKS Cluster NodeGroup`. -Connect the `ARN` output socket of the `nodegroup-profile-role` AWS IAM Role to -the `Node Role ARN` input socket of your `demo-nodegroup` NodeGroup. +Connect the `ARN` Output Socket of the `nodegroup-profile-role` AWS IAM Role to +the `Node Role ARN` Input Socket of your `demo-nodegroup` NodeGroup. ### Create an AWS IAM Policy Statement @@ -291,7 +291,7 @@ the `Node Role ARN` input socket of your `demo-nodegroup` NodeGroup. Add an `AWS IAM Policy Statement` within the `nodegroup-profile-role` AWS IAM Role frame. -Set the component name to `nodegroup-profile-role-policy`. +Set the Component name to `nodegroup-profile-role-policy`. Set the `Effect` to `Allow`. @@ -304,17 +304,17 @@ Set the `[0]` value for the `Action` array to `sts:AssumeRole`. Add an `AWS IAM Service Principal` within the `nodegroup-profile-role` AWS IAM Role frame. -Set the component name to `ec2.amazonaws.com`. +Set the Component name to `ec2.amazonaws.com`. Set the `Service` to `ec2.amazonaws.com`. -Connect the `Principal` output socket of the `ec2.amazonaws.com` AWS IAM AWS -Service Principal to the `Principal` input socket of your +Connect the `Principal` Output Socket of the `ec2.amazonaws.com` AWS IAM AWS +Service Principal to the `Principal` Input Socket of your `nodegroup-profile-role-policy` AWS IAM Policy Statement. ### Connect Additional Access Policies to the IAM Role -Add 3 `Aws IAM Role Policy` component to the `nodegroup-profile-role` AWS IAM +Add 3 `Aws IAM Role Policy` Component to the `nodegroup-profile-role` AWS IAM Role frame. Configure it as follows: @@ -325,46 +325,46 @@ Configure it as follows: | AmazonEC2ContainerRegistryReadOnly | arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly | | AmazonEKSWorkerNodePolicy | arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy | -Connect the `RoleName` output socket of the `nodegroup-profile-role` to the -`RoleName` input socket of each of the AWS IAM Role Policy components in that +Connect the `RoleName` Output Socket of the `nodegroup-profile-role` to the +`RoleName` Input Socket of each of the AWS IAM Role Policy Components in that frame. -### Create a Security Group component for the NodeGroup +### Create a Security Group Component for the NodeGroup ![Create Security Group](./aws-eks/create-ec2-security-group-for-nodegroup.png) Add a `Security Group` to your `demo-eks-cluster` eks cluster frame. -Set the component name to `demo-eks-nodegroup-sg`. +Set the Component name to `demo-eks-nodegroup-sg`. Set the `GroupName` to `demo-eks-nodegroup-sg`. Set the `Description` to `Security Group for the EKS NodeGroup` -Connect the `Security Group ID` output socket of `demo-eks-nodegroup-sg` -component to the `Security Group ID` input socket of the `demo-nodegroup` frame. +Connect the `Security Group ID` Output Socket of `demo-eks-nodegroup-sg` +Component to the `Security Group ID` Input Socket of the `demo-nodegroup` frame. -### Create an Ingress Rule component +### Create an Ingress Rule Component ![Create Ingress Rule](./aws-eks/create-security-group-ingress-for-nodegroup.png) Add a `Security Group Rule (Ingress)` to your `demo-eks-cluster` eks cluster frame. -Set the component name to `nodegroup-all-protocol-all-ports`. +Set the Component name to `nodegroup-all-protocol-all-ports`. Set the `Description` to `Ingress to allow all ports and protocols on the NodeGroup`. Set the `TrafficPort` to `-1/-1`. -Connect the `Security Group ID` output socket of `demo-eks-nodegroup-sg` -component to the `Security Group ID` input socket of this -`nodegroup-all-protocol-all-ports` component. +Connect the `Security Group ID` Output Socket of `demo-eks-nodegroup-sg` +Component to the `Security Group ID` Input Socket of this +`nodegroup-all-protocol-all-ports` Component. -Connect the `Security Group ID` output socket of -eks-cluster-sg`component to the`Source Traffic Security Group -ID`input socket of this`nodegroup-all-protocol-all-ports` component. +Connect the `Security Group ID` Output Socket of +eks-cluster-sg`Component to the`Source Traffic Security Group +ID`Input Socket of this`nodegroup-all-protocol-all-ports` Component. ### Apply your Change Set @@ -425,7 +425,7 @@ error: You must be logged in to the server (Unauthorized) This is because my local user does not have any access to the apiserver/nothing has been granted within the Cluster access configuration -Start in a change set named `EKS Cluster Access`. +Start in a Change Set named `EKS Cluster Access`. ### Update EKS Cluster Access Config @@ -434,7 +434,7 @@ Start in a change set named `EKS Cluster Access`. Update the `demo-eks-cluster` `accessConfig.authenticationMode` to be `API_AND_CONFIG_MAP` -Right-click on the component and select `Update Cluster Access Config`. +Right-click on the Component and select `Update Cluster Access Config`. Note: This change needs to take effect in the cluster before you can add access policies. So you will need to retry the failed access entry actions. @@ -445,7 +445,7 @@ policies. So you will need to retry the failed access entry actions. Add an `Access Entry` to your `demo-eks-cluster` eks cluster frame. -Set the component name to `My User`. +Set the Component name to `My User`. Set the `type` to `STANDARD`. @@ -454,7 +454,7 @@ Set the `principalArn` to ``. NOTE: The `principalArn` is the ARN of the user I want to grant access to my cluster. -Add 2 `Access Policy` components to your `demo-eks-cluster` eks cluster frame. +Add 2 `Access Policy` Components to your `demo-eks-cluster` eks cluster frame. Configure them to be as follows: @@ -463,8 +463,8 @@ Configure them to be as follows: | AmazonEKSAdminPolicy | arn:aws:eks::aws:cluster-access-policy/AmazonEKSAdminPolicy | cluster | | AmazonEKSClusterAdminPolicy | arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy | cluster | -Connect the `Principal ARN` output socket of the `My User` component to the -`Principal ARN` input sockets of the Access Policy components +Connect the `Principal ARN` Output Socket of the `My User` Component to the +`Principal ARN` Input Sockets of the Access Policy Components ### Apply your Change Set @@ -515,11 +515,15 @@ of your new resources. ### Clean Up -Create a new change set called `Clean up How-to` +Create a new Change Set called `Clean up How-to` -Delete your `VPC How-to` VPC frame. All of the components inside will be marked +Delete your `VPC How-to` VPC frame. All of the Components inside will be marked for deletion. Click `Apply Change Set`. All your new resources should be deleted from your AWS account. + +## Vocabulary +In this guide bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/how-tos/aws-ha-ec2.md b/app/docs/src/how-tos/aws-ha-ec2.md index fdc91c66a0..8a5132c108 100644 --- a/app/docs/src/how-tos/aws-ha-ec2.md +++ b/app/docs/src/how-tos/aws-ha-ec2.md @@ -28,23 +28,23 @@ We will cover: All activities in this how-to happen within a configured VPC, AWS Region and AWS Credential. -Start in a change set named `EC2 HA How-to`. +Start in a Change Set named `EC2 HA How-to`. ## Walkthrough ### What it will look like -When you are through with this guide, you should have components that look like -this in your diagram: +When you are through with this guide, you should have Components that look like +this in your Diagram: ![AWS HA EC2 Diagram](./aws-ha-ec2/aws-ha-ec2-complete.png) -### Create a Loadbalancer component +### Create a Loadbalancer Component ![Create Loadbalancer](./aws-ha-ec2/create-loadbalancer.png) Add a `Loadbalancer` to your `VPC How-to` vpc frame. -Set the component name to `application-lb`. +Set the Component name to `application-lb`. Set the `LbName` to `application-alb`. @@ -54,32 +54,32 @@ Set the `LbType` to be `application`. Set the `Scheme` to be `internet-facing`. -Connect the `Subnet ID` output socket of each of the public subnet components to -the `Subnet ID` input socket of the `application-alb` component. +Connect the `Subnet ID` Output Socket of each of the public subnet Components to +the `Subnet ID` Input Socket of the `application-alb` Component. -### Create an EC2 security group component for the Loadbalancer +### Create an EC2 security group Component for the Loadbalancer ![Create Security Group](./aws-ha-ec2/create-security-group.png) Add a `Security Group` to your `application-alb` loadbalancer frame. -Set the component name to `ALB Security Group`. +Set the Component name to `ALB Security Group`. Set the `GroupName` to `ALB Security Group`. Set the `Description` to be `ALB to the world` -Connect the `Security Group ID` output socket of `ALB Security Group` component -to the `Security Group ID` input socket of the `application-alb` frame. +Connect the `Security Group ID` Output Socket of `ALB Security Group` Component +to the `Security Group ID` Input Socket of the `application-alb` frame. -### Create an Ec2 Ingress Rule component +### Create an Ec2 Ingress Rule Component ![Create Security Group](./aws-ha-ec2/create-security-group-ingress.png) Add a `Security Group Rule (Ingress)` to your `application-alb` loadbalancer frame. -Set the component name to be `alb-8080-ingress`. +Set the Component name to be `alb-8080-ingress`. Set the `Description` to be `Public traffic to HTTP 8080`. @@ -90,30 +90,30 @@ Add an `IpRange` array item. Set the `IP Range [CIDR]` to be `0.0.0.0/0` and the `Description` to be `The world`. -Connect the `Security Group ID` output socket of `ALB Security Group` component -to the `Security Group ID` input socket of this `alb-8080-ingress` component. +Connect the `Security Group ID` Output Socket of `ALB Security Group` Component +to the `Security Group ID` Input Socket of this `alb-8080-ingress` Component. -### Create a Listener component +### Create a Listener Component ![Create Listener](./aws-ha-ec2/create-listener.png) -Add a `Listener` component to your `application-alb` loadbalancer frame. +Add a `Listener` Component to your `application-alb` loadbalancer frame. -Set the component name to `HTTP:8080`. +Set the Component name to `HTTP:8080`. Set the `Port` to be `8080`. Set the `Protocol` to be `HTTP`. -Resize the frame to be large enough to fit another component. +Resize the frame to be large enough to fit another Component. ### Create a Target Group ![Create Target Group](./aws-ha-ec2/create-target-group.png) -Add a `Target Group` component to your `Listener` frame. +Add a `Target Group` Component to your `Listener` frame. -Set the component name to `app-tg`. +Set the Component name to `app-tg`. Set `TgName` to be `app-tg`. @@ -139,26 +139,26 @@ Set `Protocol` to be `HTTP`. Set `UnhealthyThresholdCount` to be `2`. -Connect the `Target Group ARN` output socket of `app-tg` component to the -`Target Group ARN` input socket of the `HTTP:8080` frame. +Connect the `Target Group ARN` Output Socket of `app-tg` Component to the +`Target Group ARN` Input Socket of the `HTTP:8080` frame. ### Create an Application Frame ![Create Application Frame](./aws-ha-ec2/create-application-frame.png) -Add a `Generic Frame` component to your `VPC` frame. +Add a `Generic Frame` Component to your `VPC` frame. -Set the component name to be `Application`. +Set the Component name to be `Application`. -Resize the frame to hold many components. +Resize the frame to hold many Components. ### Create an IAM Role ![Create IAM Role](./aws-ha-ec2/create-iam-role.png) -Add an `AWS IAM Role` component to your `Application` frame. +Add an `AWS IAM Role` Component to your `Application` frame. -Set the component name to `application-role`. +Set the Component name to `application-role`. Set the `RoleName` to `application-role`. @@ -173,7 +173,7 @@ Set the `Path` to `/si-tutorial/`. Add an `AWS IAM Policy Statement` within the `application-role` AWS IAM Role frame. -Set the component name to `allow-ec2`. +Set the Component name to `allow-ec2`. Set the `Effect` to `Allow`. @@ -188,12 +188,12 @@ Set the `[0]` value for the `Action` array to `sts:AssumeRole`. Add an `AWS IAM Service Principal` within the `application-role` AWS IAM Role frame. -Set the component name to `ec2 service`. +Set the Component name to `ec2 service`. Set the `Service` to `ec2.amazonaws.com`. -Connect the `Principal` output socket of the `ec2-service` AWS IAM AWS Service -Principal to the `Principal` input socket of your `allow-ec2` AWS IAM Policy +Connect the `Principal` Output Socket of the `ec2-service` AWS IAM AWS Service +Principal to the `Principal` Input Socket of your `allow-ec2` AWS IAM Policy Statement. ### Create an IAM Instance Profile @@ -202,75 +202,75 @@ Statement. Add an `IAM Instance Profile` to your `Application` frame. -Set the component name to `application-instance-profile-how-to`. +Set the Component name to `application-instance-profile-how-to`. Set the `InstanceProfileName` to `application-instance-profile-how-to`. Set the `Path` to `/si-tutorial/`. -Connect the `Role Name` output socket of `application-role` IAM Role component -to the `Role Name` input socket of the `application-instance-profile` IAM -Instance Profile component. +Connect the `Role Name` Output Socket of `application-role` IAM Role Component +to the `Role Name` Input Socket of the `application-instance-profile` IAM +Instance Profile Component. -### Create a Security Group component for the Application +### Create a Security Group Component for the Application ![Create Security Group](./aws-ha-ec2/create-security-group-application.png) Add a `Security Group` to your `Application` frame. -Set the component name to `application-sg` +Set the Component name to `application-sg` Set the `GroupName` to `application-sg`. Set the `Description` to be `Application Security Group` -### Create an Ec2 Ingress Rule component +### Create an Ec2 Ingress Rule Component ![Application Ingress](./aws-ha-ec2/create-application-ingress.png) Add a `Security Group Rule (Ingress)` to your `Application` frame. -Set the component name to be `application-8080-ingress`. +Set the Component name to be `application-8080-ingress`. Set the `Description` to be `8080 inbound to the node`. Set the `TrafficPort` to be `8080/tcp`. -Connect the `Security Group ID` output socket of `application-sg` component to -the `Security Group ID` input socket of this `application-8080-ingress` -component. +Connect the `Security Group ID` Output Socket of `application-sg` Component to +the `Security Group ID` Input Socket of this `application-8080-ingress` +Component. -Connect the `Security Group ID` output socket of `ALB Security Group` component -to the `Source Traffic Security Group ID` input socket of this -`application-8080-ingress` component. +Connect the `Security Group ID` Output Socket of `ALB Security Group` Component +to the `Source Traffic Security Group ID` Input Socket of this +`application-8080-ingress` Component. -### Create a Key Pair component +### Create a Key Pair Component ![Create Key Pair](./aws-ha-ec2/create-key-pair.png) Add a `Key Pair` to your `Application` frame. -Set the component name to `application-key-pair`. +Set the Component name to `application-key-pair`. Set the `KeyName` to `application-key-pair`. -### Create an AMI component +### Create an AMI Component ![Create AMI](./aws-ha-ec2/create-ami.png) Add an `AMI` to your `Application` frame. -Set the component name to be `Amazon Linux 2023`. +Set the Component name to be `Amazon Linux 2023`. Set the `ImageId` to be `ami-0ba9883b710b05ac6`. -### Create a Launch Template component +### Create a Launch Template Component ![Create Launch Template](./aws-ha-ec2/create-launch-template.png) -Add a `Launch Template` component to your `Application` frame. +Add a `Launch Template` Component to your `Application` frame. -Set the component name to `application-launch-template-how-to`. +Set the Component name to `application-launch-template-how-to`. Set the `LaunchTemplateName` to `application-launch-template-how-to`. @@ -351,27 +351,27 @@ systemctl enable flask-app systemctl start flask-app ``` -Connect the `Security Group ID` output socket of `application-sg` component to -the `Security Group ID` input socket of this `application-launch-template` -component. +Connect the `Security Group ID` Output Socket of `application-sg` Component to +the `Security Group ID` Input Socket of this `application-launch-template` +Component. -Connect the `Key Name` output socket of `application-key-pair-how-to` component -to the `Key Name` input socket of this `application-launch-template` component. +Connect the `Key Name` Output Socket of `application-key-pair-how-to` Component +to the `Key Name` Input Socket of this `application-launch-template` Component. -Connect the `ARN` output socket of `application-instance-profile` component to -the `Instance Profile ARN` input socket of this `application-launch-template` -component. +Connect the `ARN` Output Socket of `application-instance-profile` Component to +the `Instance Profile ARN` Input Socket of this `application-launch-template` +Component. -Connect the `Image ID` output socket of `Amazon Linux 2023` component to the -`Image ID` input socket of this `application-launch-template` component. +Connect the `Image ID` Output Socket of `Amazon Linux 2023` Component to the +`Image ID` Input Socket of this `application-launch-template` Component. -### Create an AutoScaling Group component +### Create an AutoScaling Group Component ![Create AutoScaling Group](./aws-ha-ec2/create-asg.png) -Add an `AutoScaling Group` component to the `Application` frame. +Add an `AutoScaling Group` Component to the `Application` frame. -Set the component name to `application-asg`. +Set the Component name to `application-asg`. Set `AutoScalingGroupName` to be `application-asg`. @@ -381,16 +381,16 @@ Set `MaxSize` to be 1. Set `MinSize` to be 0. -Connect the `Launch Template` output socket of `application-launch-template` -component to the `Launch Template` input socket of this `application-asg` -component. +Connect the `Launch Template` Output Socket of `application-launch-template` +Component to the `Launch Template` Input Socket of this `application-asg` +Component. -Connect the `Subnet ID` output socket of each of the `Public` subnet components -to the `Subnet ID` input socket of this `application-asg` component. +Connect the `Subnet ID` Output Socket of each of the `Public` subnet Components +to the `Subnet ID` Input Socket of this `application-asg` Component. -Connect the `Target Group ARN` output socket of each of the `app-tg` Target -Group to the `Target Group ARN` input socket of this `application-asg` -component. +Connect the `Target Group ARN` Output Socket of each of the `app-tg` Target +Group to the `Target Group ARN` Input Socket of this `application-asg` +Component. ### Apply your Change Set @@ -415,11 +415,15 @@ of your new resources. ### Clean Up -Create a new change set called `Clean up How-to` +Create a new Change Set called `Clean up How-to` -Delete your `VPC How-to` VPC frame. All of the components inside will be marked +Delete your `VPC How-to` VPC frame. All of the Components inside will be marked for deletion. Click `Apply Change Set`. All your new resources should be deleted from your AWS account. + +## Vocabulary +In this guide bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/how-tos/aws-iam.md b/app/docs/src/how-tos/aws-iam.md index e16e59c7f9..00d3abc81d 100644 --- a/app/docs/src/how-tos/aws-iam.md +++ b/app/docs/src/how-tos/aws-iam.md @@ -18,7 +18,7 @@ We will cover: - Creating a customer managed identity policy - Adding complex statements to the policy - Attaching our policy to a user -- Using the AWS ARN component to manipulate ARNs +- Using the AWS ARN Component to manipulate ARNs We will be creating a policy to [restrict EC2 access to a specific region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ExamplePolicies_EC2.html). @@ -28,19 +28,19 @@ We will be creating a policy to All activities in this how-to happen within a configured AWS Region and AWS Credential. -Start in a change set named `IAM How-to`. See the [AWS VPC How To](./aws-vpc.md) +Start in a Change Set named `IAM How-to`. See the [AWS VPC How To](./aws-vpc.md) for instructions on how to set this up. ## Walkthrough ### What it will look like -When you are through with this guide, you should have components that look like -this in your diagram: +When you are through with this guide, you should have Components that look like +this in your Diagram: ![AWS IAM Diagram](./aws-iam/aws-iam-complete.png) -### Create an AWS IAM Customer Managed Identity Policy component +### Create an AWS IAM Customer Managed Identity Policy Component ![AWS IAM Diagram](./aws-iam/create-managed-identity-policy.png) @@ -49,13 +49,13 @@ You can learn more about Add an AWS IAM Customer Managed Identity Policy to your `Region` frame. -Set the components name to `Only EC2 In North Virginia`. +Set the Components name to `Only EC2 In North Virginia`. Set the `Path` to `/si-howto/`. Set the `PolicyName` to `only-ec2-in-north-virginia` -### Create an AWS IAM Policy Statement component +### Create an AWS IAM Policy Statement Component ![AWS Policy Statement](./aws-iam/create-iam-policy-statement.png) @@ -68,23 +68,23 @@ Set the `Effect` to `Deny`. Add an item to the `Action` array, and set the value `ec2:*`. -### Create an AWS IAM Any component +### Create an AWS IAM Any Component ![AWS IAM Any](./aws-iam/create-iam-any.png) -Add an `AWS IAM Any` component inside your `Only EC2 In North Virginia` policy +Add an `AWS IAM Any` Component inside your `Only EC2 In North Virginia` policy frame. Set the name to `Any EC2 Resource`. -Connect the `Resource` output socket to the `Resource` input socket of your +Connect the `Resource` Output Socket to the `Resource` Input Socket of your `Only EC2 In North Virginia` statement. -### Create an AWS IAM Condition Operator component +### Create an AWS IAM Condition Operator Component ![AWS IAM Condition Operator](./aws-iam/create-condition-operator.png) -Add an `AWS IAM Condition Operator` component inside your +Add an `AWS IAM Condition Operator` Component inside your `Only EC2 In North Virginia` policy frame. Set the name to `Only allow us-east-1`. @@ -97,7 +97,7 @@ Change the `ConditionValue` from being set via socket to being set `manually`. Add an item to the `ConditionValue` array, and set the value to `us-east-1`. -Connect the `Condition` output socket to the `Condition` input socket of your +Connect the `Condition` Output Socket to the `Condition` Input Socket of your `Only EC2 In North Virginia` statement. ### Review your policy @@ -131,10 +131,10 @@ following: } ``` -Your components should be passing all their +Your Components should be passing all their [qualifications](/reference/vocabulary#Qualification). -### Create an AWS IAM User component +### Create an AWS IAM User Component ![Create IAM User](./aws-iam/create-iam-user.png) @@ -147,19 +147,19 @@ Set the `UserName` to `bobo`. Set the `Path` to `/si-howto/`. -### Create an AWS IAM User Policy component +### Create an AWS IAM User Policy Component ![Create IAM User](./aws-iam/create-iam-user-policy.png) -Add an `AWS IAM User Policy` component to your `Region` frame. +Add an `AWS IAM User Policy` Component to your `Region` frame. Set the name to `bobo EC2 Restrictions`. -Connect the `UserName` output socket of your `bobo` AWS IAM User to the -`UserName` input socket of your `bobo EC2 Restrictions` AWS IAM User Policy. +Connect the `UserName` Output Socket of your `bobo` AWS IAM User to the +`UserName` Input Socket of your `bobo EC2 Restrictions` AWS IAM User Policy. -Connect the `ARN` output socket of the `Only EC2 In North Virginia` AWS IAM -Customer Managed Identity Policy to the `Policy ARN` input socket of your +Connect the `ARN` Output Socket of the `Only EC2 In North Virginia` AWS IAM +Customer Managed Identity Policy to the `Policy ARN` Input Socket of your `bobo EC2 Restrictions` AWS IAM User Policy. ### Apply your Change Set @@ -184,7 +184,7 @@ of your new resources. ### Clean Up -Create a new change set called `Clean up IAM How-to` +Create a new Change Set called `Clean up IAM How-to` Delete your `Only EC2 In North Virginia` policy frame. @@ -212,27 +212,27 @@ Add an `S3 Bucket` in your `region` frame. Set the name to `bobo-logs`. -#### Create an IAM Policy Statement component +#### Create an IAM Policy Statement Component -Add an `AWS IAM Policy Statement` component within your Region. +Add an `AWS IAM Policy Statement` Component within your Region. Set the name to `Example Policy`. -Connect the `ARN` output socket of `bobo-logs` to the `Resource` input socket of +Connect the `ARN` Output Socket of `bobo-logs` to the `Resource` Input Socket of `Example Policy`. -#### Create an AWS ARN component +#### Create an AWS ARN Component -Add an `AWS ARN` component within your Region. +Add an `AWS ARN` Component within your Region. Set the name to `bobo-logs/*`. -Connect the `ARN` output socket of `bobo-logs` to the `ARN` input socket of +Connect the `ARN` Output Socket of `bobo-logs` to the `ARN` Input Socket of `bobo-logs/*`. Set the `resource-postfix` to `/*`. -Connect the `ARN` output socket of `bobo-logs/*` to the `Resource` input socket +Connect the `ARN` Output Socket of `bobo-logs/*` to the `Resource` Input Socket of `Example Policy`. #### Examine the Example Policy @@ -245,4 +245,8 @@ You can use this style to override or extend any ARN. #### Clean up -Abandon your `Complex ARN Example` change set. +Abandon your `Complex ARN Example` Change Set. + +## Vocabulary +In this guide bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/how-tos/aws-lambda.md b/app/docs/src/how-tos/aws-lambda.md index 1dd12e987b..73b7c50940 100644 --- a/app/docs/src/how-tos/aws-lambda.md +++ b/app/docs/src/how-tos/aws-lambda.md @@ -30,24 +30,24 @@ We will cover: All activities in this how-to happen within an AWS Region and AWS Credential. -Start in a change set named `ECR Infrastructure How-to`. +Start in a Change Set named `ECR Infrastructure How-to`. ## Walkthrough ### What it will look like -When you are through with this guide, you should have components that look like -this in your diagram: +When you are through with this guide, you should have Components that look like +this in your Diagram: ![AWS ECS Diagram](./aws-lambda/complete.png) ### Create AWS Credentials -Add an `AWS Credential` to your change set and configure your AWS credentials +Add an `AWS Credential` to your Change Set and configure your AWS credentials ### Select an AWS Region -Add an `AWS Region` to your change set and set the `region` property to +Add an `AWS Region` to your Change Set and set the `region` property to `us-east-1`. ### Create an ECR Repository @@ -56,9 +56,9 @@ Add an `AWS Region` to your change set and set the `region` property to Add an `ECR Private Repository` to your `us-east-1` region frame. -Set the component name to be `lambda-how-to-repository`. +Set the Component name to be `lambda-how-to-repository`. -Set the component type to be `Configuration Frame (down)`. +Set the Component type to be `Configuration Frame (down)`. Set the `repositoryName` to be `lambda-how-to-repository`. @@ -70,15 +70,15 @@ Set `ForceDelete` to be `true`. Add an `ECR Repository Policy` to your `demo-app-repo` repository frame. -Set the component name to be `lambda-how-to-repository policy` +Set the Component name to be `lambda-how-to-repository policy` -Set the component type to be `Configuration Frame (up)`. +Set the Component type to be `Configuration Frame (up)`. ### Create an IAM Policy Statement Add an `IAM Policy Statement` to the `lambda-how-to-repository policy` frame. -Set the component name to be `AllowLambdaAccess`. +Set the Component name to be `AllowLambdaAccess`. Set the `Sid` to be `AllowLambdaAccess`. @@ -209,17 +209,17 @@ curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}' That should give you the correct API response from the container to prove that the container has been built correctly. -### Create a new Change set +### Create a new Change Set -Create a new change set called `Lambda Infra`. +Create a new Change Set called `Lambda Infra`. ### Create an IAM Role for the Lambda ![Create IAM Role](./aws-lambda/create-iam-role-for-lambda.png) -Add an `AWS IAM Role` component to your `us-east-1` region frame. +Add an `AWS IAM Role` Component to your `us-east-1` region frame. -Set the component name to `Lambda Trust Policy`. +Set the Component name to `Lambda Trust Policy`. Set the `RoleName` to `LambdaTrustPolicy`. @@ -232,7 +232,7 @@ Set the `Description` to `IAM Role to for Lambda execution`. Add an `AWS IAM Policy Statement` within the `Lambda Trust Policy` AWS IAM Role frame. -Set the component name to `LambdaTrustPolicyStatement`. +Set the Component name to `LambdaTrustPolicyStatement`. Set the `Effect` to `Allow`. @@ -250,10 +250,10 @@ Set the value to be `lambda.amazonaws.com`. ![Create IAM Cusstomer Managed Identity Policy](./aws-lambda/create-lambda-identity-policy.png) -Add an `AWS IAM Customer Managed Identity Policy` component to your `us-east-1` +Add an `AWS IAM Customer Managed Identity Policy` Component to your `us-east-1` region frame. -Set the component name to `LambdaECRExecutionRole`. +Set the Component name to `LambdaECRExecutionRole`. Set the `RoleName` to `LambdaECRExecutionRole`. @@ -264,7 +264,7 @@ Set the `RoleName` to `LambdaECRExecutionRole`. Add an `AWS IAM Policy Statement` within the `LambdaECRExecutionRole` AWS IAM Role frame. -Set the component name to `LambdaPermission`. +Set the Component name to `LambdaPermission`. Set the `Effect` to `Allow`. @@ -276,8 +276,8 @@ Set the values to be: - `ecr:BatchGetImage` - `ecr:BatchCheckLayerAvailability` -Connect the `Repository ARN` output socket of the `lambda-how-to-repository` to -the `Resource` input socket of this `LambdaPermission` component. +Connect the `Repository ARN` Output Socket of the `lambda-how-to-repository` to +the `Resource` Input Socket of this `LambdaPermission` Component. ### Create an AWS IAM Role Policy @@ -285,13 +285,13 @@ the `Resource` input socket of this `LambdaPermission` component. Add an `AWS IAM Role Policy` to your `us-east-1` region frame. -Set the component name to `Attach Lambda ECR Permissions`. +Set the Component name to `Attach Lambda ECR Permissions`. -Connect the `RoleName` output socket of the `Lambda Trust Policy` component to -the `RoleName` of this `Attach Lambda ECR Permissions` component. +Connect the `RoleName` Output Socket of the `Lambda Trust Policy` Component to +the `RoleName` of this `Attach Lambda ECR Permissions` Component. -Connect the `ARN` output socket of the `LambdaECRExecutionRole` to the -`Policy ARN` input socket of this `Attach Lambda ECR Permissions` component. +Connect the `ARN` Output Socket of the `LambdaECRExecutionRole` to the +`Policy ARN` Input Socket of this `Attach Lambda ECR Permissions` Component. ### Create a Lambda Function @@ -299,9 +299,9 @@ Connect the `ARN` output socket of the `LambdaECRExecutionRole` to the Add a `Lambda Function` to your `us-east-1` region frame. -Set the component name to be `HelloWorldNodeFunction`. +Set the Component name to be `HelloWorldNodeFunction`. -Set the component type to be `Configuration Frame (down)`. +Set the Component type to be `Configuration Frame (down)`. Set the `FunctionName` to be `HelloWorldNodeFunction`. @@ -309,11 +309,11 @@ Set `Publish` to be `true`. Set `Architectures` to be `arm64`. -Connect the `Repository URI` output socket of the `lambda-how-to-repository` to -the `Container Image` input socket of this `HelloWorldNodeFunction` component. +Connect the `Repository URI` Output Socket of the `lambda-how-to-repository` to +the `Container Image` Input Socket of this `HelloWorldNodeFunction` Component. -Connect the `ARN` output socket of the `Lambda Trust Policy` component to the -`Role ARN` input socket of this `HelloWorldNodeFunction` component. +Connect the `ARN` Output Socket of the `Lambda Trust Policy` Component to the +`Role ARN` Input Socket of this `HelloWorldNodeFunction` Component. In order to ensure that you are setting the correct version of the container image, you can inspect the docker container manifest to ensure you set the @@ -359,7 +359,7 @@ In this case, I would set the `ContainerImageVersion` to be Add a `Lambda Permission` to your `HelloWorldNodeFunction` Lambda function frame. -Set the component name to be `FunctionPublicPermission`. +Set the Component name to be `FunctionPublicPermission`. Set `Action` to be `lambda:InvokeFunctionUrl`. @@ -376,7 +376,7 @@ Set `StatementId` to be `AllowPublicAccess`. Add a `Lambda Function Url` to your `HelloWorldNodeFunction` Lambda function frame. -Set the component name to be `FunctionPublicUrl`. +Set the Component name to be `FunctionPublicUrl`. Set the `AuthType` to be `NONE`. @@ -397,16 +397,20 @@ Click the `Apply Change Set` button to: Review the completed AWS resources by clicking the `Resource` sub-panel for each of your new resources. -Select the `FunctionPublicUrl` component on the model. Go to the `Resource Data` +Select the `FunctionPublicUrl` Component on the Model. Go to the `Resource Data` screen and you will find the `FunctionUrl`. You can visit that URL in the browser and inspect the running application. ### Clean Up -Create a new change set called `Clean up How-to` +Create a new Change Set called `Clean up How-to` -Delete all of the components. +Delete all of the Components. Click `Apply Change Set`. All your new resources should be deleted from your AWS account. + +## Vocabulary +In this guide bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/how-tos/aws-macos.md b/app/docs/src/how-tos/aws-macos.md index 0da3b72a84..17ef326b92 100644 --- a/app/docs/src/how-tos/aws-macos.md +++ b/app/docs/src/how-tos/aws-macos.md @@ -28,32 +28,32 @@ you will not be able to release the host before the 24 hour period expires. ## What it will look like when completed -When you have completed this guide, you should have components that look like -this in your diagram: +When you have completed this guide, you should have Components that look like +this in your Diagram: ![AWS macOS Diagram](./aws-macos/aws-macos-complete.png) ## Walkthrough -### Create a change set +### Create a Change Set -![Create a change set](./aws-macos/create-change-set.png) +![Create a Change Set](./aws-macos/create-change-set.png) -Create a change set named `MacOS How-to`. +Create a Change Set named `MacOS How-to`. ### Create AWS Credentials -Add a `AWS Credential` to your change set and configure your AWS credentials as +Add a `AWS Credential` to your Change Set and configure your AWS credentials as per the -[getting started guide](../tutorials/getting-started#add-an-aws-credential-component) +[getting started guide](../tutorials/getting-started#add-an-aws-credential-Component) ### Select an AWS Region ![Select an AWS Region](./aws-macos/select-an-aws-region.png) -Add a `AWS Region` to your change set. +Add a `AWS Region` to your Change Set. -Set the component name to be `us-east-1`. +Set the Component name to be `us-east-1`. Set the `region` property to `us-east-1`. @@ -61,64 +61,64 @@ Set the `region` property to `us-east-1`. ![Select an Ec2 Dedicated Host](./aws-macos/create-ec2-dedicated-host.png) -Add an `EC2 Host` component to the `us-east-1` frame. +Add an `EC2 Host` Component to the `us-east-1` frame. -Change the component type to be `Down Frame`. +Change the Component type to be `Down Frame`. -Set the component name to be `macOS dedicated host` +Set the Component name to be `macOS dedicated host` Set the `InstanceType` to be `mac2-m2pro.metal`. Set the `AvailabilityZone` to be `us-east-1c`. -Resize the frame to allow space for a child component to be inside it. +Resize the frame to allow space for a child Component to be inside it. ### Select an EC2 Instance Component -![Select an EC2 Instance](./aws-macos/create-ec2-instance-component.png) +![Select an EC2 Instance](./aws-macos/create-ec2-instance-Component.png) -Add an `EC2 Instance` component to the `macOS dedicated host` frame. +Add an `EC2 Instance` Component to the `macOS dedicated host` frame. -Set the component name to be `macos-1`. +Set the Component name to be `macos-1`. Set the `InstanceType` to be `mac2-m2pro.metal` ### Create an AMI Component -![Select an AMI](./aws-macos/create-ami-component.png) +![Select an AMI](./aws-macos/create-ami-Component.png) -Add an `AMI` component to the `us-east-1` frame. +Add an `AMI` Component to the `us-east-1` frame. -Set the component name to be `macOS Sonoma 14.6.1` +Set the Component name to be `macOS Sonoma 14.6.1` Set the `ImageId` to be `ami-083104674423416b8`. -Connect the `Image ID` output socket to the `Image ID` input socket of the -`macos-1` component. +Connect the `Image ID` Output Socket to the `Image ID` Input Socket of the +`macos-1` Component. ### Create a Security Group Component -![Select a Security Group](./aws-macos/create-security-group-component.png) +![Select a Security Group](./aws-macos/create-security-group-Component.png) -Add a `Security Group` component to the `us-east-1` frame. +Add a `Security Group` Component to the `us-east-1` frame. -Set the component name to be `macos-sg`. +Set the Component name to be `macos-sg`. Set the `GroupName` to be `macos-sg`. Set the `Description` to be `Security Group to control access to my macOS instance`. -Connect the `Security Group ID` output socket to the `Security Group ID` input -socket of the `macos-1` component. +Connect the `Security Group ID` Output Socket to the `Security Group ID` input +socket of the `macos-1` Component. ### Create a Security Group Ingress Rule Component -![Select a Security Group Rule Ingress](./aws-macos/create-security-group-ingress-component.png) +![Select a Security Group Rule Ingress](./aws-macos/create-security-group-ingress-Component.png) -Add a `Security Group Rule (Ingress)` component to the `us-east-1` frame. +Add a `Security Group Rule (Ingress)` Component to the `us-east-1` frame. -Set the component name to be `ssh ingress rule` +Set the Component name to be `ssh ingress rule` Set the `Description` to be `22 inbound to the node`. @@ -129,21 +129,21 @@ Add an `IpRange` array item. Set the `IP Range [CIDR]` to be `0.0.0.0/0` and the `Description` to be `The world`. -Connect the `Security Group ID` output socket of `macos-sg` component to the -`Security Group ID` input socket of this `ssh-ingress-rule` component. +Connect the `Security Group ID` Output Socket of `macos-sg` Component to the +`Security Group ID` Input Socket of this `ssh-ingress-rule` Component. ### Create a KeyPair Component -![Select a Key Pair](./aws-macos/create-key-pair-component.png) +![Select a Key Pair](./aws-macos/create-key-pair-Component.png) -Add a `Key Pair` component to the `us-east-1` frame. +Add a `Key Pair` Component to the `us-east-1` frame. -Set the component name to be `macos-key`. +Set the Component name to be `macos-key`. Set the `KeyName` to be `macos-key`. -Connect the `Key Name` output socket to the `Key Name` input socket of the -`macos-1` component. +Connect the `Key Name` Output Socket to the `Key Name` Input Socket of the +`macos-1` Component. ### Apply your Change Set @@ -165,11 +165,15 @@ of your new resources. ### Clean Up -Create a new change set called `Clean up How-to` +Create a new Change Set called `Clean up How-to` -Delete your `us-east-1` Region frame. All of the components inside will be +Delete your `us-east-1` Region frame. All of the Components inside will be marked for deletion. Click `Apply Change Set`. All your new resources should be deleted from your AWS account. + +## Vocabulary +In this guide bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/how-tos/aws-static-cloudfront.md b/app/docs/src/how-tos/aws-static-cloudfront.md index c1012d04e4..51567c8a39 100644 --- a/app/docs/src/how-tos/aws-static-cloudfront.md +++ b/app/docs/src/how-tos/aws-static-cloudfront.md @@ -24,24 +24,24 @@ We will cover: All activities in this how-to happen within an AWS Region and AWS Credential. -Start in a change set named `S3 Website How-to`. +Start in a Change Set named `S3 Website How-to`. ## Walkthrough ### What it will look like -When you are through with this guide, you should have components that look like +When you are through with this guide, you should have Components that look like this in your diagram: ![AWS Static CloudFront](./aws-static-cloudfront/completed.png) ### Create AWS Credentials -Add a `AWS Credential` to your change set and configure your AWS credentials +Add a `AWS Credential` to your Change Set and configure your AWS credentials ### Select an AWS Region -Add a `AWS Region` to your change set and set the `region` property to +Add a `AWS Region` to your Change Set and set the `region` property to `us-east-1`. ### Create a S3 Bucket @@ -50,13 +50,13 @@ Add a `AWS Region` to your change set and set the `region` property to Add a `Bucket` to your `us-east-1` region frame. -Set the component name to `demo.sysinitest.net`. +Set the Component name to `demo.sysinitest.net`. Set the `BucketName` to `demo.sysinitest.net`. Set the `Acl` to `private`. -Set the component type to be `Configuration Frame (down)`. +Set the Component type to be `Configuration Frame (down)`. Set the `ObjectOwnership` to be `BucketOwnerEnforced`. @@ -66,14 +66,14 @@ Set the `ObjectOwnership` to be `BucketOwnerEnforced`. Add a `Bucket Website` to your `demo.sysinitest.net` bucket frame. -Set the component name to `demo.sysinitest.net config`. +Set the Component name to `demo.sysinitest.net config`. Set the `Index Document Suffix` to be `index.html`. Set the `Error Document Key` to be `error.html`. -The `Bucket Name` input socket of this `Bucket Website` component should get -automatically connected to the `Bucket Name` output socket of `Bucket` frame. +The `Bucket Name` Input Socket of this `Bucket Website` Component should get +automatically connected to the `Bucket Name` Output Socket of `Bucket` frame. ### Create a Bucket Policy @@ -81,12 +81,12 @@ automatically connected to the `Bucket Name` output socket of `Bucket` frame. Add a `Bucket Policy` to your `demo.sysinitest.net` bucket frame. -Set the component name to `demo.sysinitest.net policy`. +Set the Component name to `demo.sysinitest.net policy`. -Set the component type to be `Configuration Frame (up)`. +Set the Component type to be `Configuration Frame (up)`. -The `Bucket Name` input socket of this `Bucket Policy` frame should get -automatically connected to the `Bucket Name` output socket of `Bucket` frame. +The `Bucket Name` Input Socket of this `Bucket Policy` frame should get +automatically connected to the `Bucket Name` Output Socket of `Bucket` frame. ### Create an IAM Policy Statement @@ -94,7 +94,7 @@ automatically connected to the `Bucket Name` output socket of `Bucket` frame. Add an `IAM Policy Statement` to your `demo.sysinitest.net policy` frame. -Set the component name to `demo.sysinitest.net policy statement`. +Set the Component name to `demo.sysinitest.net policy statement`. Set the `Sid` to be `PublicReadGetObject`. @@ -112,15 +112,15 @@ Add an `array item` to `Action` and set the value to be `s3:GetObject`. Add an `AWS ARN` to your `demo.sysinitest.net` bucket frame. -Set the component name to be `Bucket Policy Resource`. +Set the Component name to be `Bucket Policy Resource`. Set `resource-postfix` to be `/*`. -The `ARN` input socket of this `AWS ARN` component should get automatically -connected to the `ARN` output socket of `Bucket` frame. +The `ARN` Input Socket of this `AWS ARN` Component should get automatically +connected to the `ARN` Output Socket of `Bucket` frame. -Connect the `ARN` output socket of the `AWS ARN` component to the `Resource` -input socket of the `demo.sysinitest.net policy` component. +Connect the `ARN` Output Socket of the `AWS ARN` Component to the `Resource` +Input Socket of the `demo.sysinitest.net policy` Component. ### Create a Public Access Block @@ -128,7 +128,7 @@ input socket of the `demo.sysinitest.net policy` component. Add a `Bucket Block Public Access` to your `demo.sysinitest.net` bucket frame. -Set the component name to be `Bucket Access Control`. +Set the Component name to be `Bucket Access Control`. Set `BlockPublicAcls` to be `false`. @@ -138,8 +138,8 @@ Set `BlockPublicPolicy` to be `false`. Set `RestrictPublicBuckets` to be `false`. -The `Bucket Name` input socket of this `Bucket Block Public Access` component -should get automatically connected to the `Bucket Name` output socket of +The `Bucket Name` Input Socket of this `Bucket Block Public Access` Component +should get automatically connected to the `Bucket Name` Output Socket of `Bucket` frame. ### Deploy the Bucket Website @@ -163,7 +163,7 @@ Create a new changeset called `S3 Website Cloudfront How-to`. Add a `Cloudfront Origin` to your `us-east-1` region frame. -Set the component name to be `S3-Website`. +Set the Component name to be `S3-Website`. Set the `Id` to be `S3-Website`. @@ -173,9 +173,9 @@ Set `HTTPSPort` to be `443`. Set `HTTPPort` to be `80`. -Connect the `Website Endpoint` output socket of this -`demo.sysinitest.net config` component to the `Domain Name` input socket of this -`S3-Website` component. +Connect the `Website Endpoint` Output Socket of this +`demo.sysinitest.net config` Component to the `Domain Name` Input Socket of this +`S3-Website` Component. ### Create a Cloudfront Distribution @@ -183,7 +183,7 @@ Connect the `Website Endpoint` output socket of this Add a `Cloudfront Distribution` to your `us-east-1` region frame. -Set the component name to be `Website Cloudfront`. +Set the Component name to be `Website Cloudfront`. Set the `DistributionName` to be `s3-website`. @@ -191,8 +191,8 @@ Set `Enabled` to be `true`. Set `Comment` to be `Distribution for S3 Website` -Set `TargetOriginId` to be `S3-Website` (this must match the component name of -the `Cloudfront Origin` component). +Set `TargetOriginId` to be `S3-Website` (this must match the Component name of +the `Cloudfront Origin` Component). Set `ViewerProtocolPolicy` to be `Redirect HTTP to HTTPS`. @@ -208,8 +208,8 @@ Set `CloudFrontDefaultCertificate` to be `false`. Set `MinimumProtocolVersion` to be `TLSv1.2_2021`. -Connect the `Origin` output socket of the `S3-Website` component to the `Origin` -input socket of this `Website Cloudfront` component. +Connect the `Origin` Output Socket of the `S3-Website` Component to the `Origin` +Input Socket of this `Website Cloudfront` Component. ### Create a Hosted Zone @@ -217,7 +217,7 @@ input socket of this `Website Cloudfront` component. Add a `Hosted Zone` to your `us-east-1` region frame. -Set the component name to be `sysinitest.net` +Set the Component name to be `sysinitest.net` Set the `Name` to be `sysinitest.net`. @@ -231,13 +231,13 @@ next section. Add an `ACM Certificate` to your `us-east-1` region frame. -Set the component name to be `demo.sysinitest.net`. +Set the Component name to be `demo.sysinitest.net`. Set the `DomainName` to be `demo.sysinitest.net`. -Connect the `Certificate ARN` output socket of this `demo.sysinitest.net` -component to the `ACM Certificate ARN` input socket of the `Website Cloudfront` -component. +Connect the `Certificate ARN` Output Socket of this `demo.sysinitest.net` +Component to the `ACM Certificate ARN` Input Socket of the `Website Cloudfront` +Component. ### Create an ACM Validation Record @@ -245,15 +245,15 @@ Add a `Route53 Record` to your `us-east-1` region frame. ![Create Validation Record](./aws-static-cloudfront/create-validation-record.png) -Set the component name to be `demo.sysinitest.net cert validation`. +Set the Component name to be `demo.sysinitest.net cert validation`. -Connect the `Certificate Validation Options` output socket of the -`demo.sysinitest.net` component to the `Certificate Validation Options` input -socket of this `demo.sysinitest.net cert validation` component. +Connect the `Certificate Validation Options` Output Socket of the +`demo.sysinitest.net` Component to the `Certificate Validation Options` input +socket of this `demo.sysinitest.net cert validation` Component. -Connect the `Hosted Zone ID` output socket of the `sysinitest.net` component to -the `Hosted Zone ID` input socket of this `demo.sysinitest.net cert validation` -component. +Connect the `Hosted Zone ID` Output Socket of the `sysinitest.net` Component to +the `Hosted Zone ID` Input Socket of this `demo.sysinitest.net cert validation` +Component. ### Create an Cloudfront Alias Record @@ -261,15 +261,15 @@ Add a `Route53 Record` to your `us-east-1` region frame. ![Create Cloudfront Alias Record](./aws-static-cloudfront/create-cloudfront-alias-record.png) -Set the component name to be `Cloudfront Alias Record`. +Set the Component name to be `Cloudfront Alias Record`. Set the `Name` to be `demo.sysinitest.net`. -Connect the `Domain Name` output socket of the `Website Cloudfront` component to -the `cloudfront DNS` input socket of this `Cloudfront Alias Record` component. +Connect the `Domain Name` Output Socket of the `Website Cloudfront` Component to +the `cloudfront DNS` Input Socket of this `Cloudfront Alias Record` Component. -Connect the `Hosted Zone ID` output socket of the `sysinitest.net` component to -the `Hosted Zone ID` input socket of this `Cloudfront Alias Record` component. +Connect the `Hosted Zone ID` Output Socket of the `sysinitest.net` Component to +the `Hosted Zone ID` Input Socket of this `Cloudfront Alias Record` Component. ### Apply your Change Set @@ -296,11 +296,15 @@ of your new resources. ### Clean Up -Create a new change set called `Clean up How-to` +Create a new Change Set called `Clean up How-to` -Delete your `us-east-1` region frame. All of the components inside will be +Delete your `us-east-1` region frame. All of the Components inside will be marked for deletion. Click `Apply Change Set`. All your new resources should be deleted from your AWS account. + +## Vocabulary +In this guide bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/how-tos/aws-vpc.md b/app/docs/src/how-tos/aws-vpc.md index aed2e19113..d528adfef8 100644 --- a/app/docs/src/how-tos/aws-vpc.md +++ b/app/docs/src/how-tos/aws-vpc.md @@ -23,22 +23,22 @@ We will cover: ## What it will look like when completed -When you have completed this guide, you should have components that look like -this in your diagram: +When you have completed this guide, you should have Components that look like +this in your Diagram: ![AWS VPC Diagram](./aws-vpc/aws-vpc-complete.png) ## Walkthrough -### Create a change set +### Create a Change Set -![Create a change set](./aws-vpc/create-change-set.png) +![Create a Change Set](./aws-vpc/create-change-set.png) -Create a change set named `VPC How-to`. +Create a Change Set named `VPC How-to`. ### Create AWS Credentials -Add a `AWS Credential` to your change set and configure your AWS credentials +Add a `AWS Credential` to your Change Set and configure your AWS credentials @@ -46,19 +46,19 @@ Add a `AWS Credential` to your change set and configure your AWS credentials ![Select an AWS Region](./aws-vpc/select-an-aws-region.png) -Add a `AWS Region` to your change set and set the `region` property to +Add a `AWS Region` to your Change Set and set the `region` property to `us-east-1`. -### Create a VPC component +### Create a VPC Component -![Create a VPC component](./aws-vpc/create-a-vpc-component.png) +![Create a VPC Component](./aws-vpc/create-a-vpc-Component.png) Add a `VPC` to your `us-east-1` region frame. -Set the component type to be `Down Frame` and expand it to fill the region +Set the Component type to be `Down Frame` and expand it to fill the region frame. -Set the component name to be `How to VPC`. +Set the Component name to be `How to VPC`. Set the `CidrBlock` to be `10.0.0.0/16` @@ -71,7 +71,7 @@ Enable `EnableDnsResolution`. ![Create the Public Subnet Components](./aws-vpc/create-public-subnet.png) This VPC will span multiple availability zones in our AWS Region. Add 3 `Subnet` -components to your VPC frame and configure them as follows: +Components to your VPC frame and configure them as follows: | Component Name | `CidrBlock` | `AvailabilityZone` | `IsPublic` | | -------------- | ------------- | ------------------ | ---------- | @@ -79,52 +79,52 @@ components to your VPC frame and configure them as follows: | Public 2 | 10.0.144.0/20 | us-east-1b | true | | Public 3 | 10.0.160.0/20 | us-east-1c | true | -Set the component type for each of the public subnet components to be +Set the Component type for each of the public subnet Components to be `Configuration Frame (down)`. ### Create the NAT Gateway Components ![Create the NAT Gateway Components](./aws-vpc/create-nat-gateway.png) -Add a `NAT Gateway` component to each of the `Public` subnet frames. +Add a `NAT Gateway` Component to each of the `Public` subnet frames. -Set name names of the component to be `NAT Gateway (1|2|3)` - the index should +Set name names of the Component to be `NAT Gateway (1|2|3)` - the index should align with the subnet it is inside. ### Create the Elastic IPs for each NAT Gateway ![Create the Elastic IPs for each NAT Gateway](./aws-vpc/create-elastic-ip.png) -To each of the `Public` subnet frames, add an `Elastic IP` component. +To each of the `Public` subnet frames, add an `Elastic IP` Component. -Set the names of the components to be `NAT Gateway IP (1|2|3)` - the index +Set the names of the Components to be `NAT Gateway IP (1|2|3)` - the index should align with the subnet it is inside, and match the `NAT Gateway` -component. +Component. -Connect the `Allocation ID` output socket of the `Elastic IP` component to the -`Allocation ID` input socket of the `NAT Gateway` component. The connections +Connect the `Allocation ID` Output Socket of the `Elastic IP` Component to the +`Allocation ID` Input Socket of the `NAT Gateway` Component. The connections should be in the same subnet. ### Create the Public Route Table Component ![Create the Public Route Table Component](./aws-vpc/create-public-route-table.png) -Add a `Route Table` component to the VPC frame. +Add a `Route Table` Component to the VPC frame. -Set the component type to be `Configuration Frame (down)`. +Set the Component type to be `Configuration Frame (down)`. -Set the component name to be `Public Route Table`. +Set the Component name to be `Public Route Table`. -Connect the `Subnet ID` output socket of the Public `Subnet` components to the -`Subnet ID` input socket of the `Public Route Table` component. +Connect the `Subnet ID` Output Socket of the Public `Subnet` Components to the +`Subnet ID` Input Socket of the `Public Route Table` Component. ### Create a Route Component ![Create a Route Component](./aws-vpc/create-route.png) -Add a `Route` component to the `Public Route Table` frame. +Add a `Route` Component to the `Public Route Table` frame. -Set the component name to be `Route to Internet`. +Set the Component name to be `Route to Internet`. Set `DestinationCidrBlock` to be `0.0.0.0/0`. @@ -132,27 +132,27 @@ Set `DestinationCidrBlock` to be `0.0.0.0/0`. ![Create IGW](./aws-vpc/create-igw.png) -Add an `Internet Gateway` component to the VPC frame. +Add an `Internet Gateway` Component to the VPC frame. Set the name to be `IGW`. -Connect the `Gateway ID` output socket of the `IGW` component to the -`Gateway ID` input socket of the `Route to Internet` component in the +Connect the `Gateway ID` Output Socket of the `IGW` Component to the +`Gateway ID` Input Socket of the `Route to Internet` Component in the `Public Route Table` frame. ### Create the Private Subnet Components ![Create the Private Subnet Components](./aws-vpc/create-private-subnet.png) -Add 3 `Subnet` components to your VPC frame and configure them as follows: +Add 3 `Subnet` Components to your VPC frame and configure them as follows: -| component name | `CidrBlock` | `AvailabilityZone` | +| Component name | `CidrBlock` | `AvailabilityZone` | | -------------- | ------------ | ------------------ | | Private 1 | 10.0.0.0/19 | us-east-1a | | Private 2 | 10.0.32.0/19 | us-east-1b | | Private 3 | 10.0.64.0/19 | us-east-1c | -Set the component type for each of the public subnet components to be +Set the Component type for each of the public subnet Components to be `Configuration Frame (down)`. ### Create the Private Route Table Components @@ -164,28 +164,28 @@ To each of the `Private` subnet frames, add a `Route Table` Component. Set the name to be `Private Route Table 1(2|3)` - the index should align with the subnet frame it is inside. -Set the component type for each of the `Private Route Table` components to be +Set the Component type for each of the `Private Route Table` Components to be `Configuration Frame (down)`. ### Create the Private Route Components ![Create the Private Route Components](./aws-vpc/create-private-route.png) -Add a `Route` component to each of the `Private Route Table` frames. +Add a `Route` Component to each of the `Private Route Table` frames. -Set the component name to be `Route to Internet (1|2|3)` - the index should +Set the Component name to be `Route to Internet (1|2|3)` - the index should align with the route table frame it is inside. Set `DestinationCidrBlock` to be `0.0.0.0/0`. -Connect the output socket `NAT Gateway ID` of `NAT Gateway 1` component to the -`NAT Gateway ID` input socket of `Route to Internet 1` component. +Connect the Output Socket `NAT Gateway ID` of `NAT Gateway 1` Component to the +`NAT Gateway ID` Input Socket of `Route to Internet 1` Component. -Connect the output socket `NAT Gateway ID` of `NAT Gateway 2` component to the -`NAT Gateway ID` input socket of `Route to Internet 2` component. +Connect the Output Socket `NAT Gateway ID` of `NAT Gateway 2` Component to the +`NAT Gateway ID` Input Socket of `Route to Internet 2` Component. -Connect the output socket `NAT Gateway ID` of `NAT Gateway 3` component to the -`NAT Gateway ID` input socket of `Route to Internet 3` component. +Connect the Output Socket `NAT Gateway ID` of `NAT Gateway 3` Component to the +`NAT Gateway ID` Input Socket of `Route to Internet 3` Component. ### Apply your Change Set @@ -196,7 +196,7 @@ Workspace. Click the `Apply Change Set` button to: -- Create a VPC component +- Create a VPC Component - Create 6 Subnets - Create an Internet Gateway - Create 3 Elastic IPs and 3 NAT Gateways @@ -211,11 +211,15 @@ of your new resources. ### Clean Up -Create a new change set called `Clean up VPC How-to` +Create a new Change Set called `Clean up VPC How-to` -Delete your `VPC How-to` VPC frame. All of the components inside will be marked +Delete your `VPC How-to` VPC frame. All of the Components inside will be marked for deletion. Click `Apply Change Set`. All your new resources should be deleted from your AWS account. + +## Vocabulary +In this guide bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/reference/vocabulary.md b/app/docs/src/reference/vocabulary.md index a5fa150f71..a5528d964a 100644 --- a/app/docs/src/reference/vocabulary.md +++ b/app/docs/src/reference/vocabulary.md @@ -68,17 +68,17 @@ cloud providers, etc. ## Configuration Frame (down) -A "down" frame is one where the output sockets of the frame will automatically +A "down" frame is one where the Output Sockets of the frame will automatically connect to any components placed within the frame. ## Configuration Frame (up) -An "up" frame is one where the output sockets of the components within the frame +An "up" frame is one where the Output Sockets of the components within the frame will connect to the input sockets of the frame. ## Edge -A representation of a relationship between one component's output socket and +A representation of a relationship between one component's Output Socket and another component's input socket. ## Entity @@ -156,3 +156,9 @@ is referred to as a Schema Variant. Secrets are encrypted data stored for a given type of credential. They are defined by a credential component. + +## View + +Views are a uniquely named and organized collection of components built to create +representations of infrastructure configurations that are semantically relevant +to a given workflow or user. diff --git a/app/docs/src/tutorials/actions-and-resources.md b/app/docs/src/tutorials/actions-and-resources.md index 7136014068..186b18ea97 100644 --- a/app/docs/src/tutorials/actions-and-resources.md +++ b/app/docs/src/tutorials/actions-and-resources.md @@ -15,30 +15,30 @@ To follow along, you should: 3. You should have your System Initiative workspace open in another window. -## Create a change set +## Create a Change Set -![Create a change set](./actions-and-resources/create-a-change-set.png) +![Create a Change Set](./actions-and-resources/create-a-change-set.png) -Click the create change set button. +Click the create Change Set button. -Name your new change set `Actions Tutorial`, and click the `Create change set` +Name your new Change Set `Actions Tutorial`, and click the `Create Change Set` button. -## Add an AWS Credential component and set its properties +## Add an AWS Credential Component and set its properties -![Add an AWS Credential component and set its properties](./actions-and-resources/add-an-aws-credential-and-set-its-properties.png) +![Add an AWS Credential Component and set its properties](./actions-and-resources/add-an-aws-credential-and-set-its-properties.png) Click `AWS Credential` from the AWS category of the asset pallete, and drop it -on the diagram canvas. +on the Diagram canvas. -`Resize` the component until it fills most of the visible canvas by dragging the +`Resize` the Component until it fills most of the visible canvas by dragging the lower right corner of the frame. -Name your AWS Credential component `Actions`. +Name your AWS Credential Component `Actions`. Click the `Select/add secret` button of the `AWS Credential` property. -If you have completed the Getting Started tutorial, you may have a credential +If you have completed the Getting Started tutorial, you may have a Credential already present you can use. If so, select it, and move on to the next section. If not, click the `Add Secret` button. @@ -46,27 +46,27 @@ If not, click the `Add Secret` button. Fill in your AWS accounts `Access Key Id` and `Secret Access Key`. [Refer to the AWS documentation if you do not know what they are](https://aws.amazon.com/blogs/security/how-to-find-update-access-keys-password-mfa-aws-management-console/). -Click `Store Secret` to securely encrypt and save your secret. +Click `Store Secret` to securely encrypt and save your Secret. -## Add an AWS Region component and set its properties +## Add an AWS Region Component and set its properties -![Add an AWS Region component and set its properties](./actions-and-resources/add-an-aws-region-component-and-set-its-properties.png) +![Add an AWS Region Component and set its properties](./actions-and-resources/add-an-aws-region-Component-and-set-its-properties.png) -Click `Region` from the AWS category of the asset pallete, and drop it on the -diagram canvas. +Click `Region` from the AWS category of the Asset pallete, and drop it on the +Diagram canvas. -`Resize` the component until it fills the credential frame. +`Resize` the Component until it fills the Credential frame. -Name your AWS Region component `Northern Virginia`. +Name your AWS Region Component `Northern Virginia`. Set the `region` property to `us-east-1`. -## Add a VPC component and set its properties +## Add a VPC Component and set its properties -![Add a VPC component and set its properties](./actions-and-resources/add-a-vpc-component-and-set-its-properties.png) +![Add a VPC Component and set its properties](./actions-and-resources/add-a-vpc-Component-and-set-its-properties.png) -Click `VPC` from the AWS EC2 category of the asset pallete, and drop it on the -diagram canvas. +Click `VPC` from the AWS EC2 category of the Asset pallete, and drop it on the +Diagram canvas. Name your VPC `Tutorial Network`. @@ -77,7 +77,7 @@ Name your VPC `Tutorial Network`. Click the `Actions` tab in the right side panel. You will see a list of all the available [actions](/reference/vocabulary#actions) for the VPC. -The `Tutorial Network` component was created in this change set - so System +The `Tutorial Network` Component was created in this Change Set - so System Initiative has automatically enqueued the `Create VPC` action for you. ## Apply the Change Set @@ -96,7 +96,7 @@ Press the `Escape` key or click on an empty area of the canvas to select the workspace itself. Notice that there is a create action for the `VPC Tutorial Network`. All the -actions enqueued for a change set will be shown here. +actions enqueued for a Change Set will be shown here. Click `Apply Change Set`. @@ -165,19 +165,19 @@ Close the panel by clicking the `X`. ![Create another Change Set](./actions-and-resources/create-another-change-set.png) To finish creating your VPC, you need to add a valid `CidrBlock`. To do that, -you need to create a new change set. +you need to create a new Change Set. -Click the `Create change set` button. +Click the `Create Change Set` button. -Name your change set `Fix VPC`. +Name your Change Set `Fix VPC`. -Click `Create change set`. +Click `Create Change Set`. ## Add the CidrBlock property to your VPC ![Add the CidrBlock property to your VPC](./actions-and-resources/add-the-cidrblock-property-to-your-vpc.png) -Select the `Tutorial Network` VPC component. +Select the `Tutorial Network` VPC Component. Set the `CidrBlock` property to `10.0.0.0/24`. @@ -187,12 +187,12 @@ Set the `CidrBlock` property to `10.0.0.0/24`. Hit `Escape` or click on the diagram background to select the workspace. -Your create action is still enqueued, so this change set shows no proposed +Your create action is still enqueued, so this Change Set shows no proposed actions. Click `Apply Change Set`. -Confirm that you want to apply this change set by clicking `Apply Changes` in +Confirm that you want to apply this Change Set by clicking `Apply Changes` in the modal. ## Try to create the VPC again @@ -271,7 +271,7 @@ has not done so yet. ![Refreshing the Tutorial Network Resource](./actions-and-resources/refreshing-the-tutorial-network-resource.png) -Click the `Tutorial Network` VPC component on the diagram. +Click the `Tutorial Network` VPC Component on the diagram. Click the `Resource` tab in the right side panel. @@ -282,20 +282,20 @@ Click the `Refresh Resource` button, above the `Resource` tab, to ensure you have the most up to date resource data. ::: tip You can also refresh the resource data from the `Diagram Outline` in the -left panel. Hover over the components entry, and click the small `Refresh` icon. +left panel. Hover over the Components entry, and click the small `Refresh` icon. ::: -## Create a new change set +## Create a new Change Set -![Create a new change set](./actions-and-resources/create-a-new-change-set-part-3.png) +![Create a new Change Set](./actions-and-resources/create-a-new-change-set-part-3.png) Now we will update some properties of our VPC, and add -Click the `Create change set` button. +Click the `Create Change Set` button. -Name your change set `Update VPC`. +Name your Change Set `Update VPC`. -Click `Create change set`. +Click `Create Change Set`. ## Update the properties of the Tutorial Network VPC @@ -305,9 +305,9 @@ Select the `Tutorial Network` VPC. Click the `Component` tab. -Set the component type to `Configuration Frame (Down)`. +Set the Component type to `Configuration Frame (Down)`. -`Resize` the frame large enough to hold a new component. +`Resize` the frame large enough to hold a new Component. Set the `EnableDnsHostnames` property to true. @@ -322,7 +322,7 @@ Click the `Actions` tab in the right side panel. Toggle the `Update VPC Attributes` action to `on`. This will update the `Tutorial Network` VPC resource to reflect your changed -component properties when the change set is applied. +Component properties when the Change Set is applied. ## Add a Subnet and set its properties @@ -351,16 +351,16 @@ Subnet. Click the `...` button next to the `Subnet Create` action. You will see that it is `Waiting On` the manual action to update the VPC. -When you apply the change set, the action to update the attributes will run +When you apply the Change Set, the action to update the attributes will run first. If it succeeds, then the action to create your Subnet will run. ## Apply the Change Set -![Apply the change set](./actions-and-resources/apply-the-change-set-the-end.png) +![Apply the Change Set](./actions-and-resources/apply-the-change-set-the-end.png) Click `Apply Change Set`. -Confirm that you want to apply this change set by clicking `Apply Changes` in +Confirm that you want to apply this Change Set by clicking `Apply Changes` in the modal. ## Observe the action order @@ -395,7 +395,7 @@ Click the `Apply Changes` button in the modal to confirm. In this tutorial you learned: -- How to use the Actions tab to enable/disable an action in a change set +- How to use the Actions tab to enable/disable an action in a Change Set - Enqueued actions can be seen in the changes tab - Enqueued actions are persisent across change-sets until they succeed - Actions are executed in order according to their configuration relationships @@ -405,3 +405,7 @@ In this tutorial you learned: - Updating resources requires changing both properties and enqueing an action - Actions set a models resource value through their return value - Resources can be refreshed as needed, to ensure an accurate view of the system + +## Vocabulary +In this tutorial bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/tutorials/creating-components.md b/app/docs/src/tutorials/creating-components.md index e9d941f89c..588b6498e8 100644 --- a/app/docs/src/tutorials/creating-components.md +++ b/app/docs/src/tutorials/creating-components.md @@ -1,7 +1,7 @@ # Creating Components This tutorial will teach you how to create new -[components](/reference/vocabulary#components). +[Components](/reference/vocabulary#Components). To follow along, you should: @@ -10,27 +10,27 @@ To follow along, you should: 2. You should have your System Initiative workspace open in another window. -This tutorial shows you how to create components and add functions to them. +This tutorial shows you how to create Components and add functions to them. It's focus is on introducing you to the user interface and various high level concepts. For deeper details on writing specific function types, [see the reference guides](../reference/index.md). :::tip -While creating components and writing functions does require you to write +While creating Components and writing functions does require you to write TypeScript, don't worry if you aren't familiar with the language. System Initiative functions tend to be quite short and easy to reason about. You'll pick it up. ::: -## Create a change set +## Create a Change Set -Click the create change set button. +Click the create Change Set button. -Name your new change set `Creating Components` +Name your new Change Set `Creating Components` -Click the `Create change set` button. +Click the `Create Change Set` button. ## Switch to the Customize Screen @@ -38,7 +38,7 @@ Click the `Beaker` icon to switch to the customize screen. ## Create a new Hello World Component -![Create a new Hello World Component](./creating-components/create-a-new-hello-world-component.png) +![Create a new Hello World Component](./creating-Components/create-a-new-hello-world-Component.png) Click the `New Asset` button (represented by a `+` icon) in the Assets pallete in the left side panel. @@ -53,13 +53,13 @@ of the screen. :::tip Assets are anything you might need to use in System Initiative - today, they are -synonymous with components. +synonymous with Components. ::: ## Set the Hello World meta-data -![Set the Hello World meta-data](./creating-components/set-the-hello-world-meta-data.png) +![Set the Hello World meta-data](./creating-Components/set-the-hello-world-meta-data.png) Set the `Category` to `Tutorial`. @@ -69,12 +69,12 @@ Set the `Description` to `Hello World`. Set the `color` to `#6cdcf8`. -## Add properties to the Hello World schema +## Add properties to the Hello World Schema -![Add properties](./creating-components/add-properties.png) +![Add properties](./creating-Components/add-properties.png) -In the center of the screen is a text editor showing the empty schema of your -`Hello World` component. +In the center of the screen is a text editor showing the empty Schema of your +`Hello World` Component. The code will look like this when you are finished: @@ -107,7 +107,7 @@ function main() { } ``` -This will create a component with two properties: +This will create a Component with two properties: - _Hello_: a string that must be all lowercase - _Tags_: an array of Key/Value objects @@ -116,13 +116,13 @@ Here is how you would write it yourself, step by step. ### 1. Schema function -You define your components schema by writing a TypeScript function named +You define your Components schema by writing a TypeScript function named `main()`. The function begins by creating a new `AssetBuilder()`, stored in a variable named `asset`. :::tip -This `builder` pattern is a recurring one in schema definition. You will create +This `builder` pattern is a recurring one in Schema definition. You will create new `Builder` objects, then call functions to configure them, and finally call `.build()` to output the final definition. @@ -138,7 +138,7 @@ string property will be added. The new prop definition starts with a `new PropBuilder()`, on which you will call functions on to configure your property. -- `setName` sets the properties name as it will appear in the component +- `setName` sets the properties name as it will appear in the Component attributes panel; in this case, `KeyName`. - `setKind` specifies the datatype for this property; in this case, `string`. - `setWidget` controls how this property is rendered in the attributes panel; @@ -183,40 +183,40 @@ auto-format your function as you go. ### 4. Return the compiled asset -With all your properties added to the schema, you can now return the compiled +With all your properties added to the Schema, you can now return the compiled asset definition with `return asset.build()`. ## Regenerate the asset -![Regenerate Asset](./creating-components/regenerate-asset.png) +![Regenerate Asset](./creating-Components/regenerate-asset.png) Click the `Regenerate Asset` button in the right-side panel. -This will execute your schema definition function and update System Initiative -with the new schema. +This will execute your Schema definition function and update System Initiative +with the new Schema. -## Check your new component +## Check your new Component -![Check your component](./creating-components/check-your-component.png) +![Check your Component](./creating-Components/check-your-Component.png) Click the `Graph` icon to switch to the modeling screen. -Click the `Hello World` component from the Tutorial section of your Assets -panel, and drop it on the diagram. +Click the `Hello World` Component from the Tutorial section of your Assets +panel, and drop it on the Diagram. -Name your `Hello World` component `First Component`. +Name your `Hello World` Component `First Component`. You will see that you have the following properties: - Hello, an empty string field that accepts only lowercase letters - Tags, an array of Key/Value objects -## Add a qualification function +## Add a Qualification function -![Add qualification function](./creating-components/add-qualification-function.png) +![Add Qualification function](./creating-Components/add-qualification-function.png) Click the `Beaker` icon to switch back to the customize screen. Ensure you -`Hello World` asset is selected. +`Hello World` Asset is selected. In the `Asset Functions` panel in the left pane, click the `Attach Function` button, represented by the blue links icon, and select `+ New Function`. @@ -228,24 +228,24 @@ Name your Qualification `helloWorldTags`. ## Set the qualifications meta-data -![Qualification Metadata](./creating-components/qualification-metadata.png) +![Qualification Metadata](./creating-Components/qualification-metadata.png) Set the `Display Name` to `Hello World Tags` ## Write the qualification function -![Write Qualification](./creating-components/write-qualification.png) +![Write Qualification](./creating-Components/write-qualification.png) -Ensure that any `Hello World` components have a tag with the key `Super` and +Ensure that any `Hello World` Components have a tag with the key `Super` and value is `Duper`. The code will look like this when you are finished: ```typescript -async function main(component: Input): Promise { +async function main(Component: Input): Promise { let result: "failure" | "success" = "failure"; let message = "Must have a tag of Super:Duper."; - for (const tag of component.domain.Tags) { + for (const tag of Component.domain.Tags) { if (tag.Key == "Super" && tag.Value == "Duper") { result = "success"; message = "You are Super Duper!"; @@ -278,20 +278,20 @@ helpful message. Finally, return the `result` and `message`. -## Check your new qualification function +## Check your new Qualification function -![Check Qualification](./creating-components/check-qualification.png) +![Check Qualification](./creating-Components/check-qualification.png) Click the `Graph` icon to switch to the modeling screen. -Select your `Hello World` component on the diagram. +Select your `Hello World` Component on the Diagram. Select the Qualifications sub-panel, and see that your `Hello World Tags` function is failing. ## Clean Up -Abandon your change set to clean up. +Abandon your Change Set to clean up. ## Congratulations @@ -299,17 +299,21 @@ In this tutorial you learned: - How to add a new Asset - Configure its meta-data -- Define its schema -- Regenerate the asset to update its schema -- Inspect your new asset -- Add a qualification function -- Write qualification function in TypeScript +- Define its Schema +- Regenerate the Asset to update its Schema +- Inspect your new Asset +- Add a Qualification function +- Write Qualification function in TypeScript ## Next Steps To learn more, explore the reference documentation: - [Asset Schema Reference](/reference/asset/schema.md) for more information on - how to author asset schema, including input and output sockets. + how to author Asset Schema, including Input Sockets and Output Sockets. - [Asset Function Reference](/reference/asset/function.md) for more information on how to write functions + +## Vocabulary +In this tutorial bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/tutorials/editing-components-and-contributing.md b/app/docs/src/tutorials/editing-components-and-contributing.md index 47d781e218..bff515200b 100644 --- a/app/docs/src/tutorials/editing-components-and-contributing.md +++ b/app/docs/src/tutorials/editing-components-and-contributing.md @@ -1,52 +1,52 @@ # Editing, Updating, Installing and Contributing Components This tutorial will teach you how to create new -[components](/reference/vocabulary#components). +[Components](/reference/vocabulary#Components). To follow along, you should: 1. Finish the [Getting Started tutorial](./getting-started), to have basic knowledge of System Initiative. -2. Finished the [Creating Components tutorial](./creating-components.md). +2. Finished the [Creating Components tutorial](./creating-Components.md). 3. You should have your System Initiative workspace open in another window. -This tutorial shows you how to edit existing components and functions, and +This tutorial shows you how to edit existing Components and functions, and contribute them back to the community. It's focus is on introducing you to the user interface and various high level concepts. For deeper details on writing specific function types, [see the reference guides](../reference/index.md). -## Create a change set +## Create a Change Set -![Create a change set](./editing-components-and-contributing/create-change-set.png) +![Create a Change Set](./editing-Components-and-contributing/create-change-set.png) -Click the create change set button. +Click the create Change Set button. -Name your new change set `Editing Components` +Name your new Change Set `Editing Components` -Click the `Create change set` button. +Click the `Create Change Set` button. ## Create a Generic Frame -![Create a Generic Frame](./editing-components-and-contributing/create-a-generic-frame.png) +![Create a Generic Frame](./editing-Components-and-contributing/create-a-generic-frame.png) -Click the `Generic Frame` from the Asset panel, then place it on the diagram canvas. +Click the `Generic Frame` from the Asset panel, then place it on the Diagram canvas. Name it `Editing Frame`. ## Switch to the Customize Screen -![Switch to the Customize Screen](./editing-components-and-contributing/switch-to-customize-screen.png) +![Switch to the Customize Screen](./editing-Components-and-contributing/switch-to-customize-screen.png) Click the `Beaker` icon to switch to the customize screen. ## Edit the Generic Frame Schema -![Edit the Generic Frame Schema](./editing-components-and-contributing/edit-the-generic-frame-schema.png) +![Edit the Generic Frame Schema](./editing-Components-and-contributing/edit-the-generic-frame-schema.png) -Select the `Generic Frame` asset from the Assets panel in the left of the customize screen. +Select the `Generic Frame` Asset from the Assets panel in the left of the customize screen. Click the `Edit` button, in the upper-right side of the meta-data. @@ -54,7 +54,7 @@ This will create a new `Editing` version of the Generic Frame. ## Add a new property to the Generic Frame -![Edit the Generic Frame Schema](./editing-components-and-contributing/add-a-new-property-to-the-generic-frame.png) +![Edit the Generic Frame Schema](./editing-Components-and-contributing/add-a-new-property-to-the-generic-frame.png) Add a new `Awesome` boolean property to the `Generic Frame`. @@ -78,78 +78,78 @@ Click `Regenerate Asset` when you are done. ## Upgrade to your new Generic Frame -![Upgrade to your new Generic Frame](./editing-components-and-contributing/upgrade-to-your-new-generic-frame.png) +![Upgrade to your new Generic Frame](./editing-Components-and-contributing/upgrade-to-your-new-generic-frame.png) Click the `Graph` icon to switch to the modeling screen. Select your `Editing Frame` generic frame. Notice that a `Lightning Bolt` icon appears next to your generic frame in the -diagram outliner, on the diagram, and next to its title in the attribute panel. +diagram outliner, on the Diagram, and next to its title in the attribute panel. This indicates that there is a new version of the Generic Frame asset which -this component can be upgraded to. +this Component can be upgraded to. Click the `Upgrade` icon in the attribute panel to upgrade your `Editing Frame`. -![Now with more awesome](./editing-components-and-contributing/now-with-more-awesome.png) +![Now with more awesome](./editing-Components-and-contributing/now-with-more-awesome.png) It will now have a property named `Awesome` with a true/false check-box! ## Edit a function -![Edit a function](./editing-components-and-contributing/edit-a-function.png) +![Edit a function](./editing-Components-and-contributing/edit-a-function.png) Click the `Beaker` icon to switch to the customize screen. -Select the `Key Pair` asset from the AWS EC2 category. +Select the `Key Pair` Asset from the AWS EC2 category. Select the `si:awsKeyPairCreateAction`. Click the `Edit` icon next to the functions name in the right side panel. -This will automatically create a new `Editing` version of the `Key Pair` asset, +This will automatically create a new `Editing` version of the `Key Pair` Asset, along with an `Editing` version of the function itself. Any changes made to this function will only impact assets that have been upgraded to the editing -version of the asset. +version of the Asset. -## Abandon your change set +## Abandon your Change Set -![Edit a function](./editing-components-and-contributing/abandon-change-set.png) +![Edit a function](./editing-Components-and-contributing/abandon-change-set.png) -Since both of these are useful working assets, abandon your change set to +Since both of these are useful working assets, abandon your Change Set to ensure your edits are not persisted by clicking the `Abandon Change Set` button -(the trash can icon next to the change set selector.) +(the trash can icon next to the Change Set selector.) ## Updating Assets from System Initiative -![Updating Assets from System Initiative](./editing-components-and-contributing/updating-assets-from-system-initiative.png) +![Updating Assets from System Initiative](./editing-Components-and-contributing/updating-assets-from-system-initiative.png) You can update assets as new versions are published from System Initiative from -the customize screen. If an asset can be updated, you will see an `Update All` -button above the asset list, and specific assets will have the same icon next +the customize screen. If an Asset can be updated, you will see an `Update All` +button above the Asset list, and specific assets will have the same icon next to their entry in the list, and next to their title in the right side panel, if they have an update available. ## Install New Assets from System Initiative -![Install New Assets from System Initiative](./editing-components-and-contributing/install-new-assets-from-system-initiative.png) +![Install New Assets from System Initiative](./editing-Components-and-contributing/install-new-assets-from-system-initiative.png) New assets published by System Initiative can be installed by clicking the `New Assets` sub-panel of the Assets tab on the customize screen. -Select the asset you want to install from the list on the left. You can then +Select the Asset you want to install from the list on the left. You can then inspect its source code by clicking through the drop-downs in the center panel. -Install the asset by clicking the `Install Module` button. +Install the Asset by clicking the `Install Module` button. ## Contributing Assets to System Initiative -![Contributing Assets to System Initiative](./editing-components-and-contributing/contributing-assets-to-system-initiative.png) +![Contributing Assets to System Initiative](./editing-Components-and-contributing/contributing-assets-to-system-initiative.png) -If you have created or edited an asset that you want to contribute to the community, +If you have created or edited an Asset that you want to contribute to the community, you can do so once you've applied it to your workspace. -The asset will appear with a `Contribute` button (a cloud with an up arrow). -Select the asset from the list, and click the icon next to the assets name in +The Asset will appear with a `Contribute` button (a cloud with an up arrow). +Select the Asset from the list, and click the icon next to the assets name in the right side panel. You'll be notified that the code will be reviewed, and agree that by clicking the @@ -163,9 +163,13 @@ In this tutorial you learned: - Edit existing assets - Edit existing functions -- Upgrade components to new versions +- Upgrade Components to new versions - Update assets from System Initiative - Install new assets from System Initiative - Contribute assets back to System Initiative Thank you! + +## Vocabulary +In this tutorial bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/tutorials/getting-started.md b/app/docs/src/tutorials/getting-started.md index 12e52dc34f..4666a73089 100644 --- a/app/docs/src/tutorials/getting-started.md +++ b/app/docs/src/tutorials/getting-started.md @@ -20,37 +20,37 @@ To follow along, you'll need three things: Your AWS account must have a [Default VPC](https://docs.aws.amazon.com/vpc/latest/userguide/default-vpc.html) to complete the quick start guide. Most accounts do! ::: -## Creating a change set +## Creating a Change Set ![Creating a Change Set](./getting-started/creating-a-change-set.png) -Click the create [change set](../reference/vocabulary#change-set) button. +Click the create [Change Set](../reference/vocabulary#change-set) button. -Name your new change set `Getting started`, and click the `Create change set` +Name your new Change Set `Getting started`, and click the `Create Change Set` button. -## Add an AWS Credential component +## Add an AWS Credential Component -![Adding an AWS Credential component](./getting-started/add-an-aws-credential-component.png) +![Adding an AWS Credential Component](./getting-started/add-an-aws-credential-Component.png) -Click `AWS Credential` from the AWS category of the asset pallete, and drop it -on the diagram canvas. This creates a new +Click `AWS Credential` from the AWS category of the Asset pallete, and drop it +on the Diagram canvas. This creates a new [credential](../reference/vocabulary#credential) -[ component](../reference/vocabulary#component). +[ Component](../reference/vocabulary#Component). -`Resize` the component until it fills most of the visible canvas by dragging the +`Resize` the Component until it fills most of the visible canvas by dragging the lower right corner of the frame. -## Name your component +## Name your Component -![Name your component](./getting-started/name-your-component.png) +![Name your Component](./getting-started/name-your-Component.png) Click on the `AWS Credential` you just added to the canvas. The panel on the right side of your screen will show its properties. It will have a default name like `si-1234`. Change the name to be `Tutorial`. Pressing enter or clicking outside the textbox -will update the diagram with your new name. +will update the Diagram with your new name. ## Add a secret @@ -59,7 +59,7 @@ will update the diagram with your new name. Click the `Select/Add Secret` button next to the AWS Credential property. Then click `Add Secret`. -Name your secret `Tutorial Secret`. +Name your Secret `Tutorial Secret`. Fill in your AWS accounts `Access Key Id` and `Secret Access Key`. [Refer to the AWS documentation if you do not know what they are](https://aws.amazon.com/blogs/security/how-to-find-update-access-keys-password-mfa-aws-management-console/). @@ -68,20 +68,20 @@ Click `Store Secret` to securely encrypt and save your [secret](../reference/vocabulary#secret). :::tip -If you see a red hexagon in the lower corner of your AWS credential frame (its [qualification](/reference/vocabulary#qualification)) after +If you see a red hexagon in the lower corner of your AWS Credential frame (its [Qualification](/reference/vocabulary#qualification)) after this step, it means that the credentials are invalid and need to be re-entered. In some cases, you may need to also add your AWS Session Key. ::: -## Add an AWS Region component and set its properties +## Add an AWS Region Component and set its properties -![Add an AWS Region component](./getting-started/add-an-aws-region-component-and-set-its-properties.png) +![Add an AWS Region Component](./getting-started/add-an-aws-region-Component-and-set-its-properties.png) -Click on the `Region` from the AWS category of the asset pallete, and drop it -inside your `Tutorial` credential frame. +Click on the `Region` from the AWS category of the Asset pallete, and drop it +inside your `Tutorial` Credential frame. -Resize the region to fill the space inside the `Tutorial` credential frame. +Resize the region to fill the space inside the `Tutorial` Credential frame. Name your region `Northern Virginia`. @@ -91,7 +91,7 @@ Set the `region` property to `us-east-1`. ![Add an AWS EC2 Key Pair](./getting-started/add-an-aws-ec2-key-pair-and-set-its-properties.png) -Click on the `Key Pair` from the AWS EC2 category of the asset pallete, and drop +Click on the `Key Pair` from the AWS EC2 category of the Asset pallete, and drop it inside your `Northern Virginia` region frame. Name your key pair `si-tutorial`. @@ -102,7 +102,7 @@ Set the KeyName property to `si-tutorial`. ![Add an EC2 Instance](./getting-started/add-an-aws-ec2-instance-and-set-its-properties.png) -Click on the `EC2 Instance` from the AWS EC2 category of the asset pallete, and +Click on the `EC2 Instance` from the AWS EC2 category of the Asset pallete, and drop it inside your `Northern Virginia` region frame. Name your EC2 Instance `si-tutorial`. @@ -113,15 +113,15 @@ Set the `InstanceType` property to `t2.micro`. ![Connect the Key Pair to the EC2 Instance](./getting-started/connect-the-key-pair-to-the-ec2-instance.png) -Click the `Key Name` output socket of your `si-tutorial` Key Pair and connect it -to the `Key Name` input socket of your new EC2 Instance component by dragging +Click the `Key Name` Output Socket of your `si-tutorial` Key Pair and connect it +to the `Key Name` Input Socket of your new EC2 Instance Component by dragging the line between them. -## Add an AWS EC2 AMI component and set its properties +## Add an AWS EC2 AMI Component and set its properties -![Add an AWS EC2 AMI component and set its properties](./getting-started/add-an-aws-ec2-ami-component-and-set-its-properties.png) +![Add an AWS EC2 AMI Component and set its properties](./getting-started/add-an-aws-ec2-ami-Component-and-set-its-properties.png) -Click on the `AMI` from the AWS EC2 category of the asset pallete, and drop it +Click on the `AMI` from the AWS EC2 category of the Asset pallete, and drop it inside your `Northern Virginia` region frame. Name your AMI `Fedora CoreOS`. @@ -132,12 +132,12 @@ Set the `ImageId` property to `ami-068493ac5013f0936`. ![Connect the AMI to the EC2 Instance](./getting-started/connect-the-ami-to-the-ec2-instance.png) -Connect the `Image ID` output socket of your AMI component to the `Image Id` -input socket of your EC2 Instance component. +Connect the `Image ID` Output Socket of your AMI Component to the `Image Id` +Input Socket of your EC2 Instance Component. -## Apply the change set +## Apply the Change Set -![Apply the change set](./getting-started/apply-the-change-set.png) +![Apply the Change Set](./getting-started/apply-the-change-set.png) Press the Escape key, or click on the background of the canvas, to ensure the workspace itself is selected. @@ -154,10 +154,10 @@ Press the `Apply Changes` button in the dialog to confirm. ![Create the Key Pair and EC2 Instance Resources](./getting-started/create-the-key-pair-and-ec2-instance-resources.png) -Applying the change set redirects you to the `HEAD` change set, and enqueues +Applying the Change Set redirects you to the `HEAD` Change Set, and enqueues your actions. The proposed changes panel on the right side of the screen shows your two pending actions. As the actions are run on AWS, their resulting -[resources](../reference/vocabulary#resource) are added to each model. As this +[resources](../reference/vocabulary#resource) are added to each Model. As this happens, the actions will disappear from the proposed changes list. Once both actions have been run, you'll see some confetti, and the changes panel @@ -177,17 +177,17 @@ Congratulations! You have created your first resources with System Initiative. ![Clean up](./getting-started/clean-up.png) -Create a new change set called `Cleanup`. +Create a new Change Set called `Cleanup`. -Select the `Tutorial AWS Credential` component. Press the delete key. +Select the `Tutorial AWS Credential` Component. Press the delete key. -You'll be presented with a dialog confirming you want to delete the components +You'll be presented with a dialog confirming you want to delete the Components we created previously. Click Confirm. Press the escape key or click on the canvas background to select the workspace. Click the Apply Change Set button to delete your EC2 Instance and Key Pair. -Confirm you want to apply the change set. +Confirm you want to apply the Change Set. After the two delete actions are run, you will have a blank workspace, and no more resources running in AWS. @@ -197,9 +197,13 @@ more resources running in AWS. Congratulations - you've created your first resources with System Initiative. You learned how to: -- Create new change sets +- Create new Change Sets - Add a credentials and secrets -- Add components to the diagram canvas -- Configure components by setting their properties -- Connect components input and output sockets to dynamically configure them -- Execute actions and create resources by applying a change set +- Add Components to the Diagram canvas +- Configure Components by setting their properties +- Connect Components Input Sockets and Output Sockets to dynamically configure them +- Execute actions and create resources by applying a Change Set + +## Vocabulary +In this tutorial bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/tutorials/index.md b/app/docs/src/tutorials/index.md index 503ccd2e60..0966db2bd5 100644 --- a/app/docs/src/tutorials/index.md +++ b/app/docs/src/tutorials/index.md @@ -6,11 +6,14 @@ rather than explaining why things work the way they do. - [Getting Started](./getting-started.md) - learn the basics of building infrastructure and applications with System Initiative. -- [Working with components](./working-with-components.md) - how to work more - deeply with components in System Initiative. +- [Working with Components](./working-with-Components.md) - how to work more + deeply with Components in System Initiative. - [Actions and Resources](./actions-and-resources.md) - how to use actions and manage your resources. -- [Creating Components](./creating-components.md) - how to extend System +- [Creating Components](./creating-Components.md) - how to extend System Initiative by creating your own new assets. -- [Editing, Updating, and Contributing Components](./editing-components-and-contributing.md) - how to edit, upgrade, update, install and contribute assets. +- [Editing, Updating, and Contributing Components](./editing-Components-and-contributing.md) - how to edit, upgrade, update, install and contribute assets. +## Vocabulary +In this tutorial bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file diff --git a/app/docs/src/tutorials/working-with-components.md b/app/docs/src/tutorials/working-with-components.md index fbaf979f97..461bb72510 100644 --- a/app/docs/src/tutorials/working-with-components.md +++ b/app/docs/src/tutorials/working-with-components.md @@ -1,6 +1,6 @@ # Working with Components -This tutorial will teach you how to work more deeply with [components](/reference/vocabulary#components) in System Initiative. +This tutorial will teach you how to work more deeply with [Components](/reference/vocabulary#Components) in System Initiative. To follow along, you should: @@ -8,43 +8,43 @@ To follow along, you should: 2. You should have your System Initiative workspace open in another window. -## Create a change set +## Create a Change Set -![Create a change set](./working-with-components/create-a-change-set.png) +![Create a Change Set](./working-with-Components/create-a-change-set.png) -Click the create change set button. +Click the create Change Set button. -Name your new change set `Exploring Properties`, and click the `Create change set` button. +Name your new Change Set `Exploring Properties`, and click the `Create Change Set` button. -## Add a Docker Image component and set its properties +## Add a Docker Image Component and set its properties -![Add a Docker Image component and set its properties](./working-with-components/add-a-docker-image-component-and-set-its-properties.png) +![Add a Docker Image Component and set its properties](./working-with-Components/add-a-docker-image-Component-and-set-its-properties.png) -Click on `Docker Image` from the `Docker` category of the asset pallete, and drop it inside your workspace. +Click on `Docker Image` from the `Docker` category of the Asset pallete, and drop it inside your workspace. -Name your Docker Image component `nginx`. +Name your Docker Image Component `nginx`. ## Observe the Docker Images Qualification -![Observe the Docker Images Qualification](./working-with-components/observe-the-docker-images-qualification.png) +![Observe the Docker Images Qualification](./working-with-Components/observe-the-docker-images-qualification.png) -Notice the red hexagon in the lower right of your `nginx` Docker Image component. This is the [qualification](/reference/vocabulary#qualification) icon - it is warning you that your Docker Image component is misconfigured. +Notice the red hexagon in the lower right of your `nginx` Docker Image Component. This is the [qualification](/reference/vocabulary#qualification) icon - it is warning you that your Docker Image Component is misconfigured. :::tip -You can also see a components qualification status in the Diagram Outline, the Component panel, and the Qualifications sub-panel. +You can also see a Components qualification status in the Diagram Outline, the Component panel, and the Qualifications sub-panel. ::: ## Investigate the Docker Images Failing Qualification -![Investigate the Docker Image](./working-with-components/investigate-the-docker-images-failing-qualification.png) +![Investigate the Docker Image](./working-with-Components/investigate-the-docker-images-failing-qualification.png) -Click the red hexagon on you `nginx` Docker Image component. The properties panel will change to the `Qualifications` sub-panel. +Click the red hexagon on you `nginx` Docker Image Component. The properties panel will change to the `Qualifications` sub-panel. You will see that your Docker Image is failing the `Docker Image Exists` qualification, with the error message 'no image available'. ## Fixing the failing Qualification -![Fixing the Failing Qualification](./working-with-components/fixing-the-failing-qualification.png) +![Fixing the Failing Qualification](./working-with-Components/fixing-the-failing-qualification.png) Select the `Attributes` sub-panel. @@ -52,25 +52,25 @@ Set the `image` property to `nginx`. The qualification icon will then turn green, confirming that a Docker Image named `nginx` exists in the Docker Hub. -## Add a Butane component and set its properties +## Add a Butane Component and set its properties -![Add a Butane component](./working-with-components/add-a-butane-component-and-set-its-properties.png) +![Add a Butane Component](./working-with-Components/add-a-butane-Component-and-set-its-properties.png) [Butane](https://coreos.github.io/butane/) is a configuration file format used by the [Fedora CoreOS](https://fedoraproject.org/coreos/) operating system. -Click on `Butane` from the `CoreOS` category of the asset pallete, and drop it inside your workspace. +Click on `Butane` from the `CoreOS` category of the Asset pallete, and drop it inside your workspace. -Name your Butane component `Web Server Config`. +Name your Butane Component `Web Server Config`. -## Observe the systemd/units property of the Butane component +## Observe the systemd/units property of the Butane Component -![Observe the systemd units](./working-with-components/observe-the-systemd-units-property-of-the-butane-component.png) +![Observe the systemd units](./working-with-Components/observe-the-systemd-units-property-of-the-butane-Component.png) The `systemd/units` property of the `Web Server Config` takes an array (as indicated by the `[ ]` symbol in front of it). It is currently empty, and configured to be automatically set via a socket. ## Manually setting the systemd/units property -![Manually setting the systemd units property](./working-with-components/manually-setting-the-systemd-units-property.png) +![Manually setting the systemd units property](./working-with-Components/manually-setting-the-systemd-units-property.png) To manually set a property that would otherwise be configured by a socket, click the `set` dropdown, and select `manually`. @@ -79,26 +79,26 @@ Click the `Add array item` button to add an entry titled `unit[0]` to the `syste Set the `name` property of `unit[0]` to `manual-unit`. :::tip -Notice that the `Web Server Config` is now failing its qualification, as this is not a valid name for a Systemd unit file! +Notice that the `Web Server Config` is now failing its Qualification, as this is not a valid name for a Systemd unit file! ::: ## Deleting the system/units/unit[0] entry -![Deleting the System/units/unit0 entry](./working-with-components/deleting-the-system-units-unit-0-entry.png) +![Deleting the System/units/unit0 entry](./working-with-Components/deleting-the-system-units-unit-0-entry.png) To delete the `unit[0]` entry, click the trash can icon in the header. -## Connect the Docker Image component to the Butane component +## Connect the Docker Image Component to the Butane Component -![Connect the Docker Image to Butane](./working-with-components/connect-the-docker-image-component-to-the-butane-component.png) +![Connect the Docker Image to Butane](./working-with-Components/connect-the-docker-image-Component-to-the-butane-Component.png) Switch the systemd/units property to be set `via socket`. -Connect the `Container Image` output socket of your `nginx` Docker Image component to the `Container Image` input socket of your `Web Server Config` Butane component. +Connect the `Container Image` Output Socket of your `nginx` Docker Image Component to the `Container Image` Input Socket of your `Web Server Config` Butane Component. ## Observe the new system/units/unit[0] entry -![Observe the new system/units entry](./working-with-components/observe-the-new-system-units-unit-0-entry.png) +![Observe the new system/units entry](./working-with-Components/observe-the-new-system-units-unit-0-entry.png) The new `unit[0]` entry is now set via a function, as indicated by the `f(x)` icon. @@ -106,19 +106,19 @@ The `name`, `contents`, and `enabled` properties have their values inferred by t ## Viewing large properties -![Viewing large properties](./working-with-components/viewing-large-properties.png) +![Viewing large properties](./working-with-Components/viewing-large-properties.png) Some properties, such as `contents`, are too long to display in the panel. You can hover over the field and then click the icon to have them pop-out to a modal for easy viewing. ## Viewing generated code -![Viewing generated code](./working-with-components/viewing-generated-code.png) +![Viewing generated code](./working-with-Components/viewing-generated-code.png) Click the `Code` sub-panel to see the JSON code as it would be processed by Butane. ## Apply the Change Set -![Apply the Change Set](./working-with-components/apply-the-change-set.png) +![Apply the Change Set](./working-with-Components/apply-the-change-set.png) Press the Escape key, or click on the background of the canvas, to ensure the workspace itself is selected. @@ -128,43 +128,43 @@ Click the `Apply Changes` button in the modal to accept. ## Create another Change Set -![Create a new Change Set](./working-with-components/create-another-new-change-set.png) +![Create a new Change Set](./working-with-Components/create-another-new-change-set.png) -Click the `Create change set` button. +Click the `Create Change Set` button. -Name your new change set `Exploring Part 2`, and click the `Create change set` button. +Name your new Change Set `Exploring Part 2`, and click the `Create Change Set` button. ## Add an exposed port to your Docker Image -![Add an exposed port to your Docker Image](./working-with-components/add-an-exposed-port-to-your-docker-image.png) +![Add an exposed port to your Docker Image](./working-with-Components/add-an-exposed-port-to-your-docker-image.png) -Click the `Add array item` button for the `ExposedPorts` property of your `nginx` Docker Image component. +Click the `Add array item` button for the `ExposedPorts` property of your `nginx` Docker Image Component. Set the `[0]` value to `80/tcp`. -## Check the Diff for your Docker Image and Butane components +## Check the Diff for your Docker Image and Butane Components -![Check the Diff for your Docker Image and Butane Components](./working-with-components/check-the-diff-for-your-docker-image-and-butane-components.png) +![Check the Diff for your Docker Image and Butane Components](./working-with-Components/check-the-diff-for-your-docker-image-and-butane-Components.png) -Click the `Diff` sub-panel for your `nginx` Docker Image component. You'll see the currently set properties for the component, and a visual diff of the changes made in this change set (compared to the values on HEAD). +Click the `Diff` sub-panel for your `nginx` Docker Image Component. You'll see the currently set properties for the Component, and a visual diff of the changes made in this Change Set (compared to the values on HEAD). -Click your `Web Server Config` Butane component, and you'll see that the entire systemd unit files contents have been updated. +Click your `Web Server Config` Butane Component, and you'll see that the entire systemd unit files contents have been updated. ## View the Debugging information -![View the Debugging information](./working-with-components/view-the-debugging-information.png) +![View the Debugging information](./working-with-Components/view-the-debugging-information.png) -Click the `Debug` sub-panel for your `nginx` Docker Image component. Here you will find detailed debugging information about the selected components attributes, input sockets, and output sockets. This information is often useful when customizing or debugging System Initiative. +Click the `Debug` sub-panel for your `nginx` Docker Image Component. Here you will find detailed debugging information about the selected Components attributes, Input Sockets, and Output Sockets. This information is often useful when customizing or debugging System Initiative. ## Clean Up -![Clean up](./working-with-components/clean-up.png) +![Clean up](./working-with-Components/clean-up.png) -Clean up your workspace by highlighting the `nginx` Docker image and the `Web Server Config` Butane components. Press the `Delete` key on your keyboard. +Clean up your workspace by highlighting the `nginx` Docker image and the `Web Server Config` Butane Components. Press the `Delete` key on your keyboard. -Click the `Confirm` button in the dialog to acknowledge you want to delete these two components. +Click the `Confirm` button in the dialog to acknowledge you want to delete these two Components. -Click the `Apply Change Set` button. Your `nginx` and `Web Server Config` components are now removed from your workspace. +Click the `Apply Change Set` button. Your `nginx` and `Web Server Config` Components are now removed from your workspace. ## Congratulations @@ -175,6 +175,10 @@ You've explored the properties panel! You learned how to: - Adding items to arrays and maps - Delete items from arrays and maps - View large properties in a modal -- See generated code for a component -- View the diff between a component on a change set and head. -- View detailed debugging information about your components +- See generated code for a Component +- View the diff between a Component on a Change Set and HEAD. +- View detailed debugging information about your Components + +## Vocabulary +In this tutorial bits of System Initiative Vocabulary will be shown with a capital letter. +All definitions for these can be found here: [System Initative - Vocabulary](https://docs.systeminit.com/reference/vocabulary) \ No newline at end of file