Skip to content

Commit

Permalink
fix: QoL changes to zilla plus fargate instructions (#270)
Browse files Browse the repository at this point in the history
  • Loading branch information
@vordimous
vordimous authored Oct 31, 2024
1 parent 984381c commit 4187b3b
Showing 1 changed file with 145 additions and 138 deletions.
283 changes: 145 additions & 138 deletions src/how-tos/zilla-plus-aws-ecs-fargate.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,179 +38,184 @@ This Guide will walk you through deploying your first <ZillaPlus/> service on AW

- Create the below `Dockerfile` with the <ZillaPlus/> container image using the version tag you got from the previous steps. Use the `COPY` instruction to add the `zilla.yaml` below to your container image.

::: code-tabs

@tab Dockerfile
::: code-tabs

@tab Dockerfile

```Dockerfile
FROM 709825985650.dkr.ecr.us-east-1.amazonaws.com/aklivity/zilla-plus-ecr:<version>-alpine

COPY ./zilla.yaml /etc/zilla/zilla.yaml
```

@tab zilla.yaml

```yaml
---
name: http-echo
bindings:
north_tcp_server:
type: tcp
kind: server
options:
host: 0.0.0.0
port:
- 7114
routes:
- when:
- port: 7114
exit: north_http_server
north_http_server:
type: http
kind: server
routes:
- when:
- headers:
:scheme: http
exit: north_echo_server
north_echo_server:
type: echo
kind: server
telemetry:
exporters:
stdout_logs_exporter:
type: stdout
```
:::
- Optionally add files, any other files used in your `zilla.yaml` can be added to the container in the same directory as the `zilla.yaml` config.

```Dockerfile
COPY ./zilla.yaml /etc/zilla/zilla.yaml
COPY ./tls /etc/zilla/tls
COPY ./specs /etc/zilla/specs
```

```Dockerfile
FROM 709825985650.dkr.ecr.us-east-1.amazonaws.com/aklivity/zilla-plus-ecr:<version>-alpine

COPY ./zilla.yaml /etc/zilla/zilla.yaml
```

@tab zilla.yaml

```yaml
---
name: http-echo
bindings:
north_tcp_server:
type: tcp
kind: server
options:
host: 0.0.0.0
port:
- 7114
routes:
- when:
- port: 7114
exit: north_http_server
north_http_server:
type: http
kind: server
routes:
- when:
- headers:
:scheme: http
exit: north_echo_server
north_echo_server:
type: echo
kind: server
telemetry:
exporters:
stdout_logs_exporter:
type: stdout
```
- Build your image to be pushed to [Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-ecr-image.html) or another registry.

:::
::: important Before you build

::: note Adding other files
- Make sure you are logged in to the `Zilla Plus` registry to pull the base image. This is a separate log in action from any other registries (ex. If you are pushing the built image to Amazon ECR).

Any other files used in your `zilla.yaml` can be added to the container in the same directory as the `zilla.yaml` config.
```bash
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com
```

```Dockerfile
COPY ./zilla.yaml /etc/zilla/zilla.yaml
COPY ./tls /etc/zilla/tls
COPY ./specs /etc/zilla/specs
```
- Confirm the CPU Architecture you need. Use the `docker build --platform` option to match the desired [cpuArchitecture](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RuntimePlatform.html#API_RuntimePlatform_Contents) that you can configure in your ECS task.

:::
:::

- Build your image to be pushed to [Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-ecr-image.html) or another registry.

```bash
docker build -t zp-example/http-echo:v1 .
```

::: important Build with the correct Architecture
Use the `docker build --platform` option to match the desired [cpuArchitecture](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RuntimePlatform.html#API_RuntimePlatform_Contents) that you can configure in your ECS task.
:::
```bash
docker build -t zp-example/http-echo:v1 .
```

- Tag your image with the remote repository name and tag.

```bash
docker tag zp-example/http-echo:v1 [your-registry-url]/zp-example/http-echo:v1
```
```bash
docker tag zp-example/http-echo:v1 [your-registry-url]/zp-example/http-echo:v1
```

- Push your image to your remote repository.

```bash
docker push [your-registry-url]/zp-example/http-echo:v1
```
```bash
docker push [your-registry-url]/zp-example/http-echo:v1
```

## Create an AWS ECS Fargate Task for your service

> This will create the AWS ECS Fargate Task that will be used to deploy your service.

- Create an IAM role for the Task. This role will be used by the running <ZillaPlus/> container.

::: tabs
::: tabs

@tab Task role
@tab Task role

Name:
Name:

```text
ecsTaskRole_ZillaPlus
```
```text
ecsTaskRole_ZillaPlus
```

Policies:
Policies:

```text
AWSMarketplaceMeteringFullAccess
AWSMarketplaceMeteringRegisterUsage
```
```text
AWSMarketplaceMeteringFullAccess
AWSMarketplaceMeteringRegisterUsage
```

:::
:::

- If you used the Amazon ECR as your image repository, create a role with the `AmazonECSTaskExecutionRolePolicy` permission and use it as the `Task execution role` when creating the Task.

::: tabs
::: tabs

@tab Task execution role
@tab Task execution role

Name:
Name:

```text
ecsTaskExecutionRole
```
```text
ecsTaskExecutionRole
```

Policies:
Policies:

```text
AmazonECSTaskExecutionRolePolicy
```
```text
AmazonECSTaskExecutionRolePolicy
```

:::
:::

- [Create a new Task Definition](https://us-east-1.console.aws.amazon.com/ecs/v2/create-task-definition-with-json) from JSON
- Substitute `<your-registry-url>`, `<ecsTaskRole_ZillaPlus ARN>`, and `<ecsTaskExecutionRole ARN>` for their respective values.

::: code-tabs

@tab Task Definition JSON

```json
{
"family": "zilla-plus-http-echo-fargate",
"networkMode": "awsvpc",
"containerDefinitions": [
{
"name": "zp-http-echo",
"image": "<your-registry-url>/zp-example/http-echo:v1",
"portMappings": [
{
"name": "http",
"containerPort": 7114,
"hostPort": 7114,
"protocol": "tcp",
"appProtocol": "http"
}
],
"essential": true,
"command": ["start", "-v", "-e"],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/",
"mode": "non-blocking",
"awslogs-create-group": "true",
"max-buffer-size": "25m",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "ecs"
::: code-tabs

@tab Task Definition JSON

```json
{
"family": "zilla-plus-http-echo-fargate",
"networkMode": "awsvpc",
"containerDefinitions": [
{
"name": "zp-http-echo",
"image": "<your-registry-url>/zp-example/http-echo:v1",
"portMappings": [
{
"name": "http",
"containerPort": 7114,
"hostPort": 7114,
"protocol": "tcp",
"appProtocol": "http"
}
],
"essential": true,
"command": ["start", "-v", "-e"],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/",
"mode": "non-blocking",
"awslogs-create-group": "true",
"max-buffer-size": "25m",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "ecs"
}
}
}
}
],
"requiresCompatibilities": ["FARGATE"],
"taskRoleArn": "<ecsTaskRole_ZillaPlus ARN>",
"executionRoleArn": "<ecsTaskExecutionRole ARN>",
"cpu": "1 vCPU",
"memory": "3 GB"
}
```
],
"requiresCompatibilities": ["FARGATE"],
"taskRoleArn": "<ecsTaskRole_ZillaPlus ARN>",
"executionRoleArn": "<ecsTaskExecutionRole ARN>",
"cpu": "1 vCPU",
"memory": "3 GB"
}
```

:::
:::

## Create a Service from your AWS ECS Fargate Task

Expand All @@ -219,12 +224,14 @@ AmazonECSTaskExecutionRolePolicy
- [Create a Service](https://us-east-1.console.aws.amazon.com/ecs/v2/clusters/my-ecs-cluster/create-service) from your new task.
- Deployment configuration:
- Family: `zilla-plus-http-echo-fargate`
- Service name: `Your Zilla Plus HTTP Echo service`
- Service name: `my_zilla_plus_service`
- Network configuration:
- Set the VPC to be the Same as your ECS Cluster.
- Make sure the security group allows traffic over the ports defined `portMappings` of the service.
- Select the Public subnets.
- Make sure the `Public IP` flag to true.
::: important Open Service Ports
Make sure the security group allows traffic over the ports defined in the `portMappings` of the service.
:::
- `Create` the Service.

## Verify your service is running
Expand All @@ -236,13 +243,13 @@ Once the service has started with all tasks succeeding, you will see the <ZillaP
- Get the Public IP of the running Task in your service.
- Call the HTTP Echo service.

```bash
curl -d "Hello, world" -H "Content-Type: text/plain" -X "POST" http://[Task Public IP]:7114
```
```bash
curl -d "Hello, world" -H "Content-Type: text/plain" -X "POST" http://[Task Public IP]:7114
```

```output
Hello, world
```
```output
Hello, world
```

- In your Task logs, you will see a `BINDING_HTTP_REQUEST_ACCEPTED` log from the above request

Expand Down

0 comments on commit 4187b3b

Please sign in to comment.