Skip to content

Commit 7243e90

Browse files
ankitk-meankitk-me
authored
docs: Usage Instructions for Zilla Plus AWS Marketplace AMIs (aklivity#317)
1 parent 54aa061 commit 7243e90

File tree

5 files changed

+255
-4
lines changed

5 files changed

+255
-4
lines changed

‎src/.vuepress/sidebar/en.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -736,10 +736,17 @@ export const enSidebar = sidebar({
736736
},
737737
{
738738
text: "Virtual Clusters",
739+
prefix: "virtual-clusters/",
739740
link: "virtual-clusters/README.md",
740741
children: [],
741742
},
742743
"zilla-plus-on-aws-ecs-fargate.md",
744+
{
745+
text: "AWS AMI",
746+
prefix: "zilla-plus-via-aws-ami/",
747+
link: "zilla-plus-via-aws-ami/README.md",
748+
children: [],
749+
},
743750
],
744751
},
745752
],

‎src/deployment/zilla-plus-in-production/zilla-plus-via-aws-ami/README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
shortTitle: AWS AMI
3+
---
4+
5+
# Deploying Zilla Plus via AWS AMI
6+
7+
[Available in Zilla Plus](https://www.aklivity.io/products/zilla-plus)
8+
{.zilla-plus-badge .hint-container .info}
9+
10+
## Overview
11+
12+
The [Zilla Plus](https://aws.amazon.com/marketplace/seller-profile?id=b9df13e8-d3bc-41d1-bf8a-4a07aaa96e62) is an enterprise-ready, Kafka-native edge, and service proxy. It is a flexible, secure, and reliable way of creating stateless, multi-protocol API entry points into your Kafka cluster for both native and non-native Kafka clients.
13+
14+
This Guide will walk you through deploying Zilla Plus service using **AWS AMI**.
15+
16+
## Subscribe via AWS Marketplace
17+
18+
To launch a Zilla Plus instance, a subscription to the [Zilla Plus product on Amazon Marketplace](https://aws.amazon.com/marketplace/seller-profile?id=b9df13e8-d3bc-41d1-bf8a-4a07aaa96e62) is required.
19+
20+
- To get started, visit the AWS Marketplace [Product Page](https://aws.amazon.com/marketplace/seller-profile?id=b9df13e8-d3bc-41d1-bf8a-4a07aaa96e62)
21+
- `Subscribe` to the appropriate **Zilla Plus** edition:
22+
- [Zilla Plus for Amazon MSK](https://aws.amazon.com/marketplace/pp/prodview-jshnzslazfm44)
23+
- [Zilla Plus for Confluent Cloud](https://aws.amazon.com/marketplace/pp/prodview-eblxkinsqbaks)
24+
- [Zilla Plus for Redpanda](https://aws.amazon.com/marketplace/pp/prodview-sj4kquyndubiu)
25+
- You should see `Zilla Plus` listed in your [AWS Marketplace](https://console.aws.amazon.com/marketplace) subscriptions.
26+
27+
You can skip this step if you have already subscribed to Zilla Plus via AWS Marketplace.
28+
29+
## Launch Zilla Plus Instance via AMI
30+
31+
![](zilla-plus-via-ami.gif)
32+
33+
### Prerequisites
34+
35+
- A Subscription to the [Zilla Plus product on Amazon Marketplace](https://aws.amazon.com/marketplace/seller-profile?id=b9df13e8-d3bc-41d1-bf8a-4a07aaa96e62)
36+
37+
### Steps to launch a Zilla Plus instance
38+
39+
1. **Sign in to the AWS Console**
40+
- Navigate to the [EC2 Dashboard](https://console.aws.amazon.com/ec2/home#Instances:instanceState=running) in your preferred region.
41+
42+
2. **Start a New Instance**
43+
- Click `Launch Instance` and provide a name (e.g., `zilla-plus-proxy`).
44+
45+
3. **Select the Zilla Plus AMI**
46+
- Choose the subscribed **Zilla Plus AMI** from your list.
47+
48+
4. **Choose an Instance Type**
49+
- Select an instance type that fits your workload (e.g., `t3.medium` or `larger`).
50+
51+
5. **Configure Networking**
52+
- Create or select a `VPC security group` that allows access to the required ports for Zilla Plus.
53+
- Ensure the instance is launched in a subnet with **Auto-assign public IP** enabled.
54+
55+
6. **Add User Data**
56+
- Expand `Advanced details` > `User data - optional`
57+
- Paste [custom cloud-init script](#user-data) to initialize the Zilla Plus service with `zilla.yaml` configuration.
58+
- You can also use `base64-encoded` input directly by selecting `User data has already been base64 encoded` option.
59+
60+
7. **Launch the Instance**
61+
- Click `Launch Instance`.
62+
63+
### User Data
64+
65+
::: tabs
66+
67+
@tab Services Init
68+
69+
```yaml:no-line-numbers
70+
<!-- @include: amazon-msk-secure-public-access-mtls-user-data.yaml#services_init -->
71+
```
72+
73+
@tab Zilla Config Init
74+
75+
```yaml:no-line-numbers
76+
<!-- @include: amazon-msk-secure-public-access-mtls-user-data.yaml#config_init -->
77+
```
78+
79+
:::
80+
81+
::: details Complete User Data for reference
82+
83+
```yaml
84+
<!-- @include: amazon-msk-secure-public-access-mtls-user-data.yaml -->
85+
```
86+
87+
:::
88+
89+
### Verify Zilla Plus Service
90+
91+
> This checks that the services and networking were properly configured.
92+
93+
Navigate to the [EC2 running instances dashboard.](https://console.aws.amazon.com/ec2/home#Instances:instanceState=running)
94+
95+
::: note Check your selected region
96+
Make sure you have selected the desired region, ex: `US East (N. Virginia) us-east-1`.
97+
:::
98+
99+
Select the Zilla Plus instance launched to show the details.
100+
101+
Find the `Public IPv4 Address` and then SSH into the instance.
102+
103+
```bash
104+
ssh -i ~/.ssh/<key-pair.cer> ec2-user@<instance-public-ip-address>
105+
```
106+
107+
After logging in via SSH, check the status of the `zilla-plus` system service.
108+
109+
::: tabs
110+
111+
@tab Service is running
112+
113+
Verify that the `zilla-plus` service is active and logging output similar to that shown below.
114+
115+
```bash
116+
systemctl status zilla-plus.service
117+
```
118+
119+
```output:no-line-numbers
120+
zilla-plus.service - Zilla Plus
121+
Loaded: loaded (/etc/systemd/system/zilla-plus.service; enabled; vendor preset: disabled)
122+
Active: active (running) since...
123+
```
124+
125+
@tab Check Zilla Logs
126+
127+
You can get an stdout dump of the `zilla-plus.service` using `journalctl`.
128+
129+
```bash
130+
journalctl -e -u zilla-plus.service | tee -a /tmp/zilla.log
131+
```
132+
133+
```output:no-line-numbers
134+
systemd[1]: Started zilla-plus.service - Zilla Plus.
135+
...
136+
```
137+
138+
@tab Check Cloud Init Logs
139+
140+
All output from cloud-init is captured by default to `/var/log/cloud-init-output.log`. There shouldn't be any errors in this log.
141+
142+
```bash
143+
cat /var/log/cloud-init-output.log
144+
```
145+
146+
```output:no-line-numbers
147+
Cloud-init v. 22.2.2 running 'init'...
148+
```
149+
150+
:::
151+
152+
## Conclusion
153+
154+
You have successfully deployed the [Zilla Plus](https://aws.amazon.com/marketplace/seller-profile?id=b9df13e8-d3bc-41d1-bf8a-4a07aaa96e62) using AWS AMI.
155+
156+
::: tip
157+
Check out the [Troubleshooting](/support/troubleshooting-guides.md) guide if you run into any issues.
158+
:::

‎src/deployment/zilla-plus-in-production/zilla-plus-via-aws-ami/amazon-msk-secure-public-access-mtls-user-data.yaml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
#cloud-config
2+
3+
write_files:
4+
- path: /etc/zilla/zilla.yaml
5+
#region config_init
6+
content: |
7+
name: public
8+
vaults:
9+
secure:
10+
type: aws-secrets
11+
bindings:
12+
tcp_server:
13+
type: tcp
14+
kind: server
15+
options:
16+
host: 0.0.0.0
17+
port: {{ EXTERNAL_PORT }}
18+
exit: tls_server
19+
tls_server:
20+
type: tls
21+
kind: server
22+
vault: secure
23+
options:
24+
keys:
25+
- {{ EXTERNAL_KEY }}
26+
routes:
27+
- exit: kafka_proxy
28+
when:
29+
- authority: "{{ EXTERNAL_AUTHORITY }}"
30+
kafka_proxy:
31+
type: kafka-proxy
32+
kind: proxy
33+
options:
34+
external:
35+
host: "{{ EXTERNAL_HOST }}"
36+
port: {{ EXTERNAL_PORT }}
37+
internal:
38+
host: "{{ INTERNAL_HOST }}"
39+
port: {{ INTERNAL_PORT }}
40+
exit: tls_client
41+
tls_client:
42+
type: tls
43+
kind: client
44+
vault: secure
45+
options:
46+
trustcacerts: true
47+
exit: tcp_client
48+
tcp_client:
49+
type: tcp
50+
kind: client
51+
options:
52+
host: "*"
53+
port: {{ INTERNAL_PORT }}
54+
routes:
55+
- when:
56+
- authority: "{{ INTERNAL_AUTHORITY }}"
57+
telemetry:
58+
exporters:
59+
logs:
60+
type: stdout
61+
#endregion config_init
62+
63+
#region services_init
64+
runcmd:
65+
- systemctl enable amazon-ssm-agent
66+
- systemctl start amazon-ssm-agent
67+
- systemctl enable zilla-plus
68+
- systemctl start zilla-plus
69+
#endregion services_init

‎src/deployment/zilla-plus-in-production/zilla-plus-via-aws-ami/zilla-plus-via-ami.gif‎

18.8 MB
Loading

‎src/deployment/zilla-to-zilla-plus-upgrade/README.md‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,28 @@ To simplify deployment, we have curated templates for the following use cases:
3030
- [Secure Private Access](/deployment/zilla-plus-in-production/secure-private-access/README.md)
3131
- [Secure Public Access](/deployment/zilla-plus-in-production/secure-public-access/README.md)
3232

33-
However, if you have a specific use-case implemented on Zilla using custom `zilla.yaml` or want to use your existing `zilla` setup, you can upgrade Zilla service to Zilla-plus on AWS ECS Fargate.
33+
However, if you have a specific use-case implemented on Zilla using custom `zilla.yaml` or want to use your existing `zilla` setup, you can upgrade Zilla service to Zilla-plus using these options:
34+
35+
- [**AWS AMI**](#aws-ami)
36+
- [**AWS ECS Fargate**](#aws-ecs-fargate)
3437

3538
## Upgrade Process
3639

37-
To migrate from Zilla to Zilla-Plus, transfer your existing zilla.yaml configuration and related files to the Zilla-Plus container using the COPY instruction.
40+
### AWS AMI
41+
42+
[Zilla Plus](https://aws.amazon.com/marketplace/seller-profile?id=b9df13e8-d3bc-41d1-bf8a-4a07aaa96e62) is available as an **Amazon Machine Image** (AMI) through the AWS Marketplace.
43+
44+
To use your custom` zilla.yaml`, you can pass the configuration as `user data` during instance launch:
45+
46+
- Go to the `Launch Instance` wizard.
47+
- Expand `Advanced details`.
48+
- Add your `zilla.yaml` under the `User data` section using cloud-config.
49+
50+
Refer to the full guide: [Deploying Zilla Plus via AWS AMI](/deployment/zilla-plus-in-production/zilla-plus-via-aws-ami/README.me)
51+
52+
### AWS ECS Fargate
53+
54+
To migrate from Zilla to Zilla-Plus, transfer your existing zilla.yaml configuration and related files to the **Zilla Plus** container using the COPY instruction.
3855

3956
Example:
4057

@@ -50,11 +67,11 @@ Copying an entire configuration directory:
5067
COPY ./etc /etc/zilla
5168
```
5269

53-
## Deployment on AWS ECS Fargate
70+
#### Deployment on AWS ECS Fargate
5471

5572
For detailed deployment steps, refer to: [Deploy Zilla-Plus on AWS ECS Fargate](../../deployment/zilla-plus-in-production/zilla-plus-on-aws-ecs-fargate.md)
5673

57-
## Verify Your Service is Running
74+
#### Verify Your Service is Running
5875

5976
Once the service has started successfully, you should see the 'started' log message in the Zilla container logs.
6077

0 commit comments

Comments
 (0)