Skip to content

Commit f1dcbe1

Browse files
bobbyilievbobbyiliev
authored
Merge pull request #3 from MaterializeInc/operator-setup-guide
Add simple operator deploy guide
2 parents 92d48c5 + 0ccae71 commit f1dcbe1

File tree

4 files changed

+240
-3
lines changed

4 files changed

+240
-3
lines changed

‎README.md

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,15 @@ The module has been tested with:
1414
| Name | Version |
1515
|------|---------|
1616
| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
17-
| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 5.75.0 |
17+
| <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 5.0 |
1818
| <a name="requirement_helm"></a> [helm](#requirement\_helm) | ~> 2.0 |
1919
| <a name="requirement_kubernetes"></a> [kubernetes](#requirement\_kubernetes) | ~> 2.0 |
2020

2121
## Providers
2222

2323
| Name | Version |
2424
|------|---------|
25-
| <a name="provider_aws"></a> [aws](#provider\_aws) | 5.75.0 |
25+
| <a name="provider_aws"></a> [aws](#provider\_aws) | 5.75.1 |
2626

2727
## Modules
2828

@@ -96,4 +96,14 @@ The module has been tested with:
9696
| <a name="output_persist_backend_url"></a> [persist\_backend\_url](#output\_persist\_backend\_url) | S3 connection URL in the format required by Materialize using IRSA |
9797
| <a name="output_s3_bucket_name"></a> [s3\_bucket\_name](#output\_s3\_bucket\_name) | Name of the S3 bucket |
9898
| <a name="output_vpc_id"></a> [vpc\_id](#output\_vpc\_id) | VPC ID |
99+
100+
## Post-Deployment Setup
101+
102+
After successfully deploying the infrastructure with this module, you'll need to:
103+
104+
1. (Optional) Configure storage classes
105+
1. Install the [Materialize Operator](https://github.com/MaterializeInc/materialize/tree/main/misc/helm-charts/operator)
106+
1. Deploy your first Materialize environment
107+
108+
See our [Operator Installation Guide](docs/operator-setup.md) for instructions.
99109
<!-- END_TF_DOCS -->

‎docs/footer.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Post-Deployment Setup
2+
3+
After successfully deploying the infrastructure with this module, you'll need to:
4+
5+
1. (Optional) Configure storage classes
6+
1. Install the [Materialize Operator](https://github.com/MaterializeInc/materialize/tree/main/misc/helm-charts/operator)
7+
1. Deploy your first Materialize environment
8+
9+
See our [Operator Installation Guide](docs/operator-setup.md) for instructions.

‎docs/operator-setup.md

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# Installing the Materialize Operator
2+
3+
After deploying the infrastructure using this Terraform module, follow these steps to install the Materialize Operator on your EKS cluster.
4+
5+
## Prerequisites
6+
7+
- `kubectl` configured to interact with your EKS cluster
8+
- Helm 3.2.0+
9+
- AWS CLI configured with appropriate credentials
10+
11+
## Configure kubectl
12+
13+
First, update your kubeconfig to connect to the newly created EKS cluster:
14+
15+
```bash
16+
aws eks update-kubeconfig --name materialize-cluster --region <your-region>
17+
```
18+
19+
> Note: the exact authentication method may vary depending on your EKS configuration. For example, you might have to add an IAM access entry to the EKS cluster.
20+
21+
Verify the connection:
22+
23+
```bash
24+
kubectl get nodes
25+
```
26+
27+
## (Optional) Storage Configuration
28+
29+
The Materialize Operator requires fast, locally-attached NVMe storage for optimal performance. We'll set up OpenEBS with LVM Local PV for managing local volumes.
30+
31+
1. Install OpenEBS:
32+
```bash
33+
# Add the OpenEBS Helm repository
34+
helm repo add openebs https://openebs.github.io/openebs
35+
helm repo update
36+
37+
# Install OpenEBS with only Local PV enabled
38+
helm install openebs --namespace openebs openebs/openebs \
39+
--set engines.replicated.mayastor.enabled=false \
40+
--create-namespace
41+
```
42+
43+
2. Verify the installation:
44+
```bash
45+
kubectl get pods -n openebs -l role=openebs-lvm
46+
```
47+
48+
### LVM Configuration for AWS Bottlerocket nodes
49+
50+
TODO: Add more detailed instructions for setting up LVM on Bottlerocket nodes.
51+
52+
If you're using the recommended Bottlerocket AMI with the Terraform module, the LVM configuration needs to be done through the Bottlerocket bootstrap container. This is automatically handled by the EKS module using the provided user data script.
53+
54+
To verify the LVM setup:
55+
```bash
56+
kubectl debug -it node/<node-name> --image=amazonlinux:2
57+
chroot /host
58+
lvs
59+
```
60+
61+
You should see a volume group named `instance-store-vg`.
62+
63+
## Install the Materialize Operator
64+
65+
0. Clone the Materialize repository:
66+
```bash
67+
[email protected]:MaterializeInc/materialize.git
68+
cd materialize
69+
```
70+
71+
1. Create a values file for the Helm installation (save as `materialize-values.yaml`):
72+
```yaml
73+
operator:
74+
args:
75+
cloudProvider: "aws"
76+
region: "<your-aws-region>" # e.g. us-west-2
77+
localDevelopment: false
78+
awsAccountID: "<your-aws-account-id>" # e.g. 123456789012
79+
createBalancers: true
80+
createConsole: true
81+
environmentdIAMRoleARN: "<output.materialize_s3_role_arn>" # e.g. arn:aws:iam::123456789012:role/materialize-s3-role
82+
startupLogFilter: "INFO"
83+
84+
namespace:
85+
create: true
86+
name: "materialize"
87+
88+
# Adjust network policies as needed
89+
networkPolicies:
90+
enabled: true
91+
egress:
92+
enabled: true
93+
cidrs: ["0.0.0.0/0"]
94+
ingress:
95+
enabled: true
96+
cidrs: ["0.0.0.0/0"]
97+
internal:
98+
enabled: true
99+
100+
# Uncomment the following block to configure OpenEBS storage
101+
# storage:
102+
# storageClass:
103+
# create: true
104+
# name: "openebs-lvm-instance-store-ext4"
105+
# provisioner: "local.csi.openebs.io"
106+
# parameters:
107+
# storage: "lvm"
108+
# fsType: "ext4"
109+
# volgroup: "instance-store-vg"
110+
# volumeBindingMode: "WaitForFirstConsumer"
111+
```
112+
113+
2. Install the Materialize Operator:
114+
```bash
115+
helm install materialize-operator misc/helm-charts/operator \
116+
-f materialize-values.yaml
117+
```
118+
119+
3. Verify the installation:
120+
```bash
121+
kubectl get pods -n materialize
122+
```
123+
124+
## Deploy a Materialize Environment
125+
126+
1. Create a secret with the backend configuration (save as `materialize-backend-secret.yaml`):
127+
```yaml
128+
apiVersion: v1
129+
kind: Secret
130+
metadata:
131+
name: materialize-backend
132+
namespace: materialize-environment
133+
stringData:
134+
metadata_backend_url: "${terraform_output.metadata_backend_url}"
135+
persist_backend_url: "${terraform_output.persist_backend_url}"
136+
```
137+
138+
> Replace `${terraform_output.metadata_backend_url}` and `${terraform_output.persist_backend_url}` with the actual values from the Terraform output.
139+
140+
2. Create a Materialize environment (save as `materialize-environment.yaml`):
141+
```yaml
142+
apiVersion: materialize.cloud/v1alpha1
143+
kind: Materialize
144+
metadata:
145+
name: "${var.service_account_name}"
146+
namespace: materialize-environment
147+
spec:
148+
environmentdImageRef: materialize/environmentd:latest
149+
environmentdResourceRequirements:
150+
limits:
151+
memory: 16Gi
152+
requests:
153+
cpu: "2"
154+
memory: 16Gi
155+
balancerdResourceRequirements:
156+
limits:
157+
memory: 256Mi
158+
requests:
159+
cpu: "100m"
160+
memory: 256Mi
161+
backendSecretName: materialize-backend
162+
```
163+
164+
> Replace `${var.service_account_name}` with the desired name for the Materialize environment. It should be a UUID, eg `12345678-1234-1234-1234-123456789012`.
165+
166+
3. Apply the configuration:
167+
```bash
168+
kubectl create namespace materialize-environment
169+
kubectl apply -f materialize-backend-secret.yaml
170+
kubectl apply -f materialize-environment.yaml
171+
```
172+
173+
4. Monitor the deployment:
174+
```bash
175+
kubectl get materializes -n materialize-environment
176+
kubectl get pods -n materialize-environment
177+
```
178+
179+
## Troubleshooting
180+
181+
If you encounter issues:
182+
183+
1. Check operator logs:
184+
```bash
185+
kubectl logs -l app.kubernetes.io/name=materialize-operator -n materialize
186+
```
187+
188+
2. Check environment logs:
189+
```bash
190+
kubectl logs -l app.kubernetes.io/name=environmentd -n materialize-environment
191+
```
192+
193+
3. Verify the storage configuration:
194+
```bash
195+
kubectl get sc
196+
kubectl get pv
197+
kubectl get pvc -A
198+
```
199+
200+
## Cleanup
201+
202+
Delete the Materialize environment:
203+
```bash
204+
kubectl delete -f materialize-environment.yaml
205+
```
206+
207+
To uninstall the Materialize operator:
208+
```bash
209+
helm uninstall materialize-operator -n materialize
210+
```
211+
212+
This will remove the operator but preserve any PVs and data. To completely clean up:
213+
```bash
214+
kubectl delete namespace materialize
215+
kubectl delete namespace materialize-environment
216+
```

‎modules/eks/main.tf

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,16 @@ module "eks" {
1414
cluster_enabled_log_types = var.cluster_enabled_log_types
1515

1616
eks_managed_node_groups = {
17-
general = {
17+
"${var.environment}-mz-workers" = {
1818
desired_size = var.node_group_desired_size
1919
min_size = var.node_group_min_size
2020
max_size = var.node_group_max_size
2121

2222
instance_types = var.node_group_instance_types
2323
capacity_type = var.node_group_capacity_type
2424

25+
name = "${var.environment}-mz"
26+
2527
labels = {
2628
Environment = var.environment
2729
GithubRepo = "materialize"

0 commit comments

Comments
 (0)