Skip to content
This repository was archived by the owner on Oct 8, 2025. It is now read-only.

Commit c70959a

Browse files
qdzlugqdzlug
authored
chore: doc updates for automation-api changes (#183)
1 parent bf66271 commit c70959a

File tree

3 files changed

+262
-220
lines changed

3 files changed

+262
-220
lines changed

‎docs/getting_started.md‎

Lines changed: 73 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ deploy the NGINX IC or the NGINX Plus IC (with a JWT from your F5 account)
9393
#### Kubernetes
9494

9595
Although not required, installing the [CLI tool `kubectl`](https://kubernetes.io/docs/tasks/tools/)
96-
will allow you to interact with the Kubernetes cluster that you have stood up using this project. This
96+
will allow you to interact with the Kubernetes cluster that you have stood up using this project. This
9797
tool is also installed as part of the venv that is created and can be used from that directory.
9898

9999
#### Setup
@@ -116,6 +116,15 @@ other environment variables into the current shell.
116116

117117
## Post Install Configuration
118118

119+
### Stack Name
120+
121+
For AWS, Linode, or Digital Ocean deployments you will need to add the variable `PULUMI_STACK_NAME` to the environment
122+
file for the deployment at [`../config/pulumi/environment`](../config/pulumi/environment). This is the name that will
123+
be used for the provisioned Pulumi stack.
124+
125+
If you are running a `kubeconfig` deployment, the process will prompt you for the value of `PULUMI_STACK_NAME` and
126+
update the environment file for you.
127+
119128
### Kubeconfig
120129

121130
If you are using an existing kubernetes installation for this project, you will need to provide three pieces of
@@ -128,56 +137,67 @@ information to the installer:
128137
The easiest way to test this is to run the command:
129138
`kubectl --kubeconfig="yourconfig" --cluster="yourcluster" --context="yourcontext"`
130139

131-
Once you have verified you can connect to the cluster you will need to test to make sure your cluster supports the
132-
minimum required capabilities for MARA. You can test this by running the [`./bin/testcap.sh`](../bin/testcap.sh)
133-
script.
134-
135-
This script does several things:
136-
137-
1. Creates a namespace
138-
2. Creates a persistent volume claim
139-
3. Deploys a pod to test the persistent volume
140-
4. Writes to the persistent volume
141-
5. Reads from the persistent volume
142-
6. Destroys the pod
143-
7. Destroys the persistent volume
144-
8. Deploys a service and attempts to provision a `LoadBalancer` to obtain an egress IP address
145-
9. Destroys the service
146-
10. Destroys the namespace
147-
148-
If any of these tests fails the script exits with notes on the failure. These failures need to be remediated before MARA
149-
can be installed.
150-
151-
There are several utilities under the `./pulumi/python/tools` directory that are intended for use to add the necessary
152-
capabilities to a Kubernetes cluster. Note that these are not extensively tested with MARA, but are included for
153-
convenience. Please see the [README.md](../pulumi/python/tools/README.md) in that directory for additional information.
154-
Note that these tools can be installed via the [kubernetes-extras.sh](../bin/kubernetes-extras.sh)
155-
script.
156-
157140
### AWS
158141

142+
*Note:* The AWS deployment has been updated from v1.1 and no longer uses the [`../bin/start.sh`](../bin/start.sh)
143+
script for deployment. If you attempt to use the script to deploy to AWS you will receive an error message. Please
144+
use the new [`../pulumi/python/runner`](../pulumi/python/runner) program for these deployments.
145+
159146
If you are using AWS as your infrastructure provider
160147
[configuring Pulumi for AWS](https://www.pulumi.com/docs/intro/cloud-providers/aws/setup/)
161148
is necessary. If you already have run the [`./bin/setup_venv.sh`](../bin/setup_venv.sh)
162-
script, you will have the `aws` CLI tool installed in the path `./pulumi/python/venv/bin/aws`
149+
script, you will have the `aws` CLI tool installed in the path `../pulumi/python/venv/bin/aws`
163150
and you do not need to install it to run the steps in the Pulumi Guide.
164151

165152
If you want to avoid using environment variables, AWS profile and region definitions can be contained in
166-
the `config/Pulumi.<stack>.yaml`
167-
files in each project. Refer to the Pulumi documentation for details on how to do this. When you run the
168-
script [`./bin/start.sh`](../bin/start.sh) and select an AWS installation, you will be prompted to add the AWS region
169-
and profile values that will then be added to the `./config/Pulumi/Pulumi.<stack>.yaml`. This is the main configuration
170-
file for the project, although there are two other configuration files kept for the application standup and the
171-
kubernetes extras functionality. For more details on those, please see the README.md in those directories.
153+
the `config/Pulumi.<stack>.yaml` files in each project. Refer to the Pulumi documentation for details on how to do this.
154+
When you run the [`../pulumi/python/runnner`](../pulumi/python/runner) program and select your provider you will be
155+
prompted for all variables necessary to use that provider along with MARA specific variables. This information will
156+
be added to the `../config/Pulumi/Pulumi.<stack>.yaml` configuration file. This is the main configuration file for the
157+
project, although there is one other configuration file used to maintain secrets in the
158+
[`../pulumi/python/kubernetes/secrets`](./pulumi/python/kubernetes/secrets) kubernetes extras functionality.
159+
For more details on those, please see the README.md in those directories.
172160

173161
### Digital Ocean
174162

163+
*Note:* The Digital Ocean deployment has been updated from v1.1 and no longer uses the
164+
[`../bin/start.sh`](../bin/start.sh) script for deployment. If you attempt to use the script to deploy to AWS you will
165+
receive an error message. Please use the new [`../pulumi/python/runner`](../pulumi/python/runner) program for these
166+
deployments.
167+
175168
You will need to create a
176169
[Digital Ocean Personal API Token](https://docs.digitalocean.com/reference/api/create-personal-access-token/)
177-
for authentication to Digital Ocean. When you run the script [`./bin/start.sh`](../bin/start.sh) and select a Digital
178-
Ocean deployment, your token will be added to the `./config/Pulumi/Pulumi.<stack>.yaml`. This is the main configuration
179-
file for the project, although there are two other configuration files kept for the application standup and the
180-
kubernetes extras functionality. For more details on those, please see the README.md in those directories.
170+
for authentication to Digital Ocean. When you run the [`./pulumi/python/runnner`](./pulumi/python/runner) program and
171+
select your provider you will be prompted for all variables necessary to use that provider along with MARA specific
172+
variables. This information will be added to the `./config/Pulumi/Pulumi.<stack>.yaml` configuration file. This is the
173+
main configuration file for the project, although there is one other configuration file used to maintain secrets in the
174+
[`./pulumi/python/kubernetes/secrets`](./pulumi/python/kubernetes/secrets) kubernetes extras functionality.
175+
For more details on those, please see the README.md in those directories.
176+
177+
### Linode
178+
179+
*Note:* The Linode deployment has been updated from v1.1 and no longer uses the [`../bin/start.sh`](../bin/start.sh)
180+
script for deployment. If you attempt to use the script to deploy to AWS you will receive an error message. Please
181+
use the new [`../pulumi/python/runner`](../pulumi/python/runner) program for these deployments.
182+
183+
You will need to create a
184+
[Linode API Token](https://www.linode.com/docs/products/tools/linode-api/guides/get-access-token/) for authentication
185+
to Linode. When you run the [`./pulumi/python/runnner`](./pulumi/python/runner) program and
186+
select your provider you will be prompted for all variables necessary to use that provider along with MARA specific
187+
variables. This information will be added to the `./config/Pulumi/Pulumi.<stack>.yaml` configuration file. This is the
188+
main configuration file for the project, although there is one other configuration file used to maintain secrets in the
189+
[`./pulumi/python/kubernetes/secrets`](./pulumi/python/kubernetes/secrets) kubernetes extras functionality.
190+
For more details on those, please see the README.md in those directories.
191+
192+
### Kubeconfig Deployments: MicroK8s / Minikube / K3s / Other
193+
194+
Deployments that use a `kubeconfig` file to access an existing K8 installation will continue to use the
195+
[`../bin/start.sh`](../bin/start.sh) script. Additionally, these deployments are not able to build the Ingress
196+
Controller and instead need to download from the NGINX repositories. The installation of NGINX+ is supported via the
197+
use of a JWT, if desired.
198+
199+
These deployments will be moved over to use the [`../pulumi/python/runner`](../pulumi/python/runner) program in a
200+
future release, which will bring them to parity for NGINX IC build/deployment with the other infrastructures.
181201

182202
### Pulumi
183203

@@ -190,18 +210,17 @@ Pulumi documentation for additional details regarding the command and alternativ
190210

191211
## Running the Project
192212

193-
The easiest way to run the project is to run [`start.sh`](../bin/start.sh)
194-
after you have completed the installation steps. When doing so, be sure to choose the same
195-
[Pulumi stack name](https://www.pulumi.com/docs/intro/concepts/stack/)
196-
for all of your projects. Additionally, this script will prompt you for infrastructure specific configuration values.
197-
This information will be used to populate the `./config/pulumi/Pulumi.<stack>.yaml` file.
213+
Provided you have completed the installation steps, the easiest way to run the project is to run
214+
[`../pulumi/python/runner`](../pulumi/python/runner) for AWS, Linode, or Digital Ocean and
215+
[`../bin/start.sh`](../bin/start.sh) for `kubeconfig` deployments. This process will prompt you for all required
216+
variables for your deployment type. This information will be used to populate the configuration files.
198217

199218
Alternatively, you can enter into each Pulumi project directory and execute each project independently by doing
200219
`pulumi up`. Take a look at `start.sh` and dependent scripts to get a feel for the flow.
201220

202-
If you want to destroy the entire environment you can run [`destroy.sh`](../bin/destroy.sh). This script calls the
203-
correct destroy script based on the information stored in the `./config/Pulumi/Pulumi.<stack>.yaml` configuration file.
204-
Detailed information and warnings are emitted by the script as it runs.
221+
If you want to destroy the entire environment you can run [`../pulumi/python/runner`](../pulumi/python/runner) for AWS,
222+
Linode, or Digital Ocean or [`destroy.sh`](../bin/destroy.sh) for `kubeconfig` deployments.
223+
Detailed information and warnings are emitted by the process as it runs.
205224

206225
### Running the Project in a Docker Container
207226

@@ -257,6 +276,13 @@ these tools.
257276
### Cleaning Up
258277

259278
If you want to completely remove all the resources you have provisioned, run the
260-
script: [`./bin/destroy.sh`](../bin/destroy.sh).
279+
[`../pulumi/python/runner`](../pulumi/python/runner) for AWS, Linode, or Digital Ocean or
280+
[`destroy.sh`](../bin/destroy.sh) for `kubeconfig` deployments. Detailed information and warnings are emitted by the
281+
process as it runs.
261282

262283
Be careful because this will **DELETE ALL** the resources you have provisioned.
284+
285+
## Other Resources
286+
Starting with release `v1.1`, the MARA project has begun the process of transitioning the deployment logic away from
287+
BASH scripts and instead using the [Pulumi Automation API](https://www.pulumi.com/docs/guides/automation-api/) with
288+
Python. For more information on this, please see this [Design Document](../pulumi/python/automation/DESIGN.md).

‎docs/status-and-issues.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -20,24 +20,24 @@ includes the following:
2020

2121
All of these configurations use Pulumi code within Python as the Infrastructure as Code (IaaC) provider.
2222

23-
| K8 Provider | Tested / Deploy Status | Infrastructure Support | IC Options | FQDN/IP | Notes |
24-
|-----------------|--------------------------------------------------------------------------------------------------------|-----------------------------|---------------------------------|-----------------|--------------------------------------------------|
25-
| AWS EKS | ![Deploy Status](https://jenkins.mantawang.com/buildStatus/icon?job=mara_aws_prod&subject=Deploy) | Full Infrastructure Standup | Build, Pull (uses ECR) | Provided | |
26-
| Azure AKS | Yes | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | |
27-
| Digtal Ocean | ![Deploy Status](https://jenkins.mantawang.com/buildStatus/icon?job=mara_do_prod&subject=Deploy) | Full Infrastructure Standup | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | |
28-
| Google GKE | Yes | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | |
29-
| Harvester/RKE2 | Yes | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | Needs Storage, K8 LoadBalancer |
30-
| K3S | ![Deploy Status](https://jenkins.mantawang.com/buildStatus/icon?job=mara_k3s_prod&subject=Deploy) | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | |
31-
| Linode | ![Deploy Status](https://jenkins.mantawang.com/buildStatus/icon?job=mara_lke_prod&subject=Deploy) | Full Infrastructure Standup | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | |
32-
| MicroK8s | ![Deploy Status](https://jenkins.mantawang.com/buildStatus/icon?job=mara_mk8s_prod&subject=Deploy) | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | Storage, DNS, and Metallb need to be Enabled (4) |
33-
| Minikube | ![Deploy Status](https://jenkins.mantawang.com/buildStatus/icon?job=mara_minikube_prod&subject=Deploy) | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | |
34-
| Rancher Desktop | No | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | Needs Storage, K8 LoadBalancer |
23+
| K8 Provider | Tested / Deploy Status | Infrastructure Support | IC Options | FQDN/IP | Notes |
24+
|-----------------|--------------------------------------------------------------------------------------------------------|-----------------------------|-----------------------------------|-----------------|--------------------------------------------------|
25+
| AWS EKS | ![Deploy Status](https://jenkins.mantawang.com/buildStatus/icon?job=mara_aws_prod&subject=Deploy) | Full Infrastructure Standup | Build, Pull (uses ECR) | Provided | |
26+
| Azure AKS | Yes | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | |
27+
| Digtal Ocean | ![Deploy Status](https://jenkins.mantawang.com/buildStatus/icon?job=mara_do_prod&subject=Deploy) | Full Infrastructure Standup | Build, Pull (Uses DO Registry) | Provided | Requires DNS delegation to DO |
28+
| Google GKE | Yes | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | |
29+
| Harvester/RKE2 | Yes | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | Needs Storage, K8 LoadBalancer |
30+
| K3S | ![Deploy Status](https://jenkins.mantawang.com/buildStatus/icon?job=mara_k3s_prod&subject=Deploy) | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | |
31+
| Linode | ![Deploy Status](https://jenkins.mantawang.com/buildStatus/icon?job=mara_lke_prod&subject=Deploy) | Full Infrastructure Standup | Build, Pull (uses Harbor install) | Provided | |
32+
| MicroK8s | ![Deploy Status](https://jenkins.mantawang.com/buildStatus/icon?job=mara_mk8s_prod&subject=Deploy) | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | Storage, DNS, and Metallb need to be Enabled (4) |
33+
| Minikube | ![Deploy Status](https://jenkins.mantawang.com/buildStatus/icon?job=mara_minikube_prod&subject=Deploy) | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | |
34+
| Rancher Desktop | No | Kubeconfig Only (3) | NGINX / NGINX Plus (w/ JWT) (1) | Manual FQDN (2) | Needs Storage, K8 LoadBalancer |
3535

3636
### Notes:
3737

3838
1. The NGINX IC build/deploy process is currently under active development and support for IC will be standardized
3939
across all providers. Follow [#81](https://github.com/nginxinc/kic-reference-architectures/issues/81) and
40-
[#86](https://github.com/nginxinc/kic-reference-architectures/issues/86) for details. Currently, for all non-AWS
40+
[#86](https://github.com/nginxinc/kic-reference-architectures/issues/86) for details. Currently, for all `kubeconfig`
4141
environments you have the option to specify either NGINX or NGINX Plus as your IC. The latter does require an active
4242
subscription and a JWT to be included at build time. Please see the documentation for more details.
4343
2. The process via which the IP and FQDN are created and used is currently under active development, and will be

0 commit comments

Comments
 (0)