Skip to content

Commit 2e75672

Browse files
Huzefaaa2Huzefaaa2
committed
Add mkdocs docs and mermaid diagrams
1 parent 345aa16 commit 2e75672

File tree

9 files changed

+220
-4
lines changed

9 files changed

+220
-4
lines changed

‎.github/workflows/deploy.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: terraform-deploy
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
environment:
7+
description: "Target environment (dev/test/prod)"
8+
required: true
9+
default: "dev"
10+
working_dir:
11+
description: "Terraform root directory"
12+
required: true
13+
default: "examples/single-region"
14+
15+
permissions:
16+
contents: read
17+
18+
jobs:
19+
plan-apply:
20+
runs-on: ubuntu-latest
21+
environment: ${{ inputs.environment }}
22+
steps:
23+
- uses: actions/checkout@v4
24+
- uses: hashicorp/setup-terraform@v3
25+
with:
26+
terraform_version: "1.6.6"
27+
- name: Terraform init
28+
run: |
29+
cd "${{ inputs.working_dir }}"
30+
terraform init -input=false
31+
- name: Terraform plan
32+
run: |
33+
cd "${{ inputs.working_dir }}"
34+
terraform plan -out=tfplan
35+
- name: Terraform apply
36+
run: |
37+
cd "${{ inputs.working_dir }}"
38+
terraform apply -input=false tfplan

‎README.md‎

Lines changed: 45 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,9 +35,46 @@ Many Apigee Terraform examples are either low-level or incomplete for enterprise
3535

3636
## Architecture diagrams
3737

38-
- **Single-region production**: `diagrams/png/apigee-single-region.png`
39-
- **Multi-region HA**: `diagrams/png/apigee-multi-region-ha.png`
40-
- **CI/CD + Policy**: `diagrams/png/apigee-cicd-policy.png`
38+
Mermaid renders (colorful by default):
39+
40+
```mermaid
41+
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#D9F0FF","primaryTextColor":"#0F172A","secondaryColor":"#FFE1D6","tertiaryColor":"#E6FFFA","lineColor":"#334155","fontFamily":"Inter, ui-sans-serif, system-ui"}}}%%
42+
flowchart LR
43+
User((Client)) -->|HTTPS| Edge[Public DNS / Cert]
44+
Edge -->|Private / Controlled| LB[Ingress (ILB / Gateway Pattern)]
45+
LB --> Apigee[Apigee X Runtime]
46+
Apigee -->|mTLS / Private| PSC[Private Service Connect]
47+
PSC --> Backends[(GCP Services / Private Backends)]
48+
Apigee --> Logs[Cloud Logging]
49+
Apigee --> Mon[Cloud Monitoring]
50+
```
51+
52+
```mermaid
53+
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#E0F2FE","primaryTextColor":"#0F172A","secondaryColor":"#FCE7F3","tertiaryColor":"#ECFCCB","lineColor":"#334155","fontFamily":"Inter, ui-sans-serif, system-ui"}}}%%
54+
flowchart LR
55+
User((Client)) --> DNS[Global DNS / Traffic Policy]
56+
DNS --> R1[Region A Ingress]
57+
DNS --> R2[Region B Ingress]
58+
R1 --> A[Apigee X Instance A]
59+
R2 --> B[Apigee X Instance B]
60+
A --> Backends[(Private Backends)]
61+
B --> Backends
62+
A --> Obs[Central Observability]
63+
B --> Obs
64+
```
65+
66+
```mermaid
67+
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#DCFCE7","primaryTextColor":"#0F172A","secondaryColor":"#FEF3C7","tertiaryColor":"#EDE9FE","lineColor":"#334155","fontFamily":"Inter, ui-sans-serif, system-ui"}}}%%
68+
flowchart LR
69+
Dev[Developer] --> PR[Pull Request]
70+
PR --> CI[CI: fmt/validate/security]
71+
CI -->|pass| Plan[Terraform Plan]
72+
Plan --> Review[Approval Gate]
73+
Review --> Apply[Terraform Apply]
74+
Apply --> Drift[Scheduled Drift Detection]
75+
CI --> Policy[OPA/Conftest Policy Set]
76+
Policy --> CI
77+
```
4178

4279
Mermaid sources:
4380
- `diagrams/mermaid/apigee-single-region.mmd`
@@ -60,6 +97,11 @@ Deploy to GitHub Pages:
6097
mkdocs gh-deploy --force
6198
```
6299

100+
Suggested reading order:
101+
102+
- `docs/index.md`
103+
- `docs/13-implementation.md`
104+
63105
---
64106

65107
## Repository layout

‎diagrams/png/apigee-cicd-policy.png‎

-76.5 KB
Binary file not shown.

‎diagrams/png/apigee-multi-region-ha.png‎

-133 KB
Binary file not shown.

‎diagrams/png/apigee-single-region.png‎

-92.4 KB
Binary file not shown.

‎docs/12-ci-cd.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ This repo includes copy-paste templates for enterprise pipelines.
66

77
Template:
88
- `ci-templates/github-actions.yml`
9+
Deploy workflow (manual):
10+
- `.github/workflows/deploy.yml`
911

1012
Stages:
1113
- fmt

‎docs/13-implementation.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Implementation Guide (Enterprise)
2+
3+
This guide explains why the stack exists, what each component does, why enterprises adopt this pattern, and the step-by-step implementation flow.
4+
5+
## Why this stack is required
6+
7+
Enterprises adopting Apigee X face the same problems:
8+
9+
- Platform setup is fragmented across scripts, consoles, and partial Terraform examples.
10+
- Networking prerequisites and service networking peering are easy to misconfigure.
11+
- Security teams require least-privilege IAM, auditability, and CMEK where available.
12+
- Platform teams need consistent, repeatable rollouts across dev/test/prod.
13+
14+
This stack addresses those issues by providing a single, opinionated baseline that is:
15+
16+
- Secure-by-default
17+
- Repeatable across environments
18+
- Clear about dependencies and ordering
19+
- Compatible with Stacks or plain Terraform
20+
21+
## What it does (component by component)
22+
23+
### Networking
24+
25+
- Enables required APIs for Apigee and Service Networking.
26+
- Creates a dedicated VPC for Apigee (or can be adapted for Shared VPC).
27+
- Reserves a peering range and establishes the Service Networking connection.
28+
29+
### Apigee Organization
30+
31+
- Creates the Apigee org bound to the GCP project.
32+
- Connects the org to the authorized network (VPC peering) for runtime.
33+
- Optionally sets CMEK for org runtime DB encryption.
34+
35+
### Instances (runtime)
36+
37+
- Creates Apigee runtime instances in one or more regions.
38+
- Optionally configures instance-level CMEK.
39+
40+
### Environments and Attachments
41+
42+
- Creates Apigee environments (dev/test/prod).
43+
- Attaches environments to one or more runtime instances.
44+
45+
### Envgroups and Attachments
46+
47+
- Creates envgroups with hostnames.
48+
- Attaches environments to envgroups to expose APIs.
49+
50+
### IAM
51+
52+
- Creates service accounts used by platform automation.
53+
- Binds project-level roles (least privilege by default).
54+
55+
### KMS (CMEK)
56+
57+
- Creates KMS key ring and crypto keys.
58+
- Optionally binds IAM to allow Apigee to use keys.
59+
60+
## Why enterprises adopt this
61+
62+
- **Compliance:** CMEK support and policy-as-code are mandatory for regulated industries.
63+
- **Governance:** Stacks and CI pipelines centralize approval gates and drift detection.
64+
- **Repeatability:** Standard patterns reduce on-call incidents and migration risk.
65+
- **Security:** Private ingress + least privilege IAM reduces attack surface.
66+
67+
## Step-by-step implementation
68+
69+
### 1) Decide deployment model
70+
71+
- Use **Modules** for local runs and CI pipelines.
72+
- Use **Stacks** for multi-environment orchestration in Terraform Cloud/Enterprise.
73+
74+
### 2) Select an example
75+
76+
Single-region (recommended first):
77+
78+
```
79+
cd examples/single-region
80+
cp terraform.tfvars.example terraform.tfvars
81+
```
82+
83+
Multi-region HA:
84+
85+
```
86+
cd examples/multi-region-ha
87+
cp terraform.tfvars.example terraform.tfvars
88+
```
89+
90+
### 3) Configure required inputs
91+
92+
- `project_id`, `region`, `analytics_region`
93+
- `network_name`, `peering_prefix_length`
94+
- `instance_name` or `primary_instance_name`/`secondary_instance_name`
95+
- `envgroup_hostnames`
96+
97+
Optional (enterprise):
98+
99+
- KMS key ring + crypto keys
100+
- IAM service accounts and project roles
101+
102+
### 4) Run Terraform
103+
104+
```
105+
terraform init
106+
terraform plan
107+
terraform apply
108+
```
109+
110+
### 5) Validate outcomes
111+
112+
- Apigee org exists and is bound to the VPC
113+
- Instances are active in the target regions
114+
- Environments are attached to instances
115+
- Envgroups are created and bound to hostnames
116+
117+
### 6) Extend with runtime stack
118+
119+
- Implement ingress, DNS, and observability in `stacks/runtime/components/*`.
120+
- Attach ingress to envgroups/hostnames.
121+
122+
## Common pitfalls
123+
124+
- Missing APIs (enable `apigee.googleapis.com` and `servicenetworking.googleapis.com`).
125+
- VPC peering range conflicts.
126+
- Missing IAM bindings for CMEK usage.
127+
- Incorrect attachment ordering (envs must exist before attachments).
128+
129+
## Recommended next steps
130+
131+
- Add CI pipelines (GitHub Actions or GitLab) using templates in `ci-templates/`.
132+
- Add policy gates with Conftest/OPA.
133+
- Split state per environment to reduce blast radius.

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ Day-2 guides:
3232
- [Multi-Environment Strategy](10-multi-env.md)
3333
- [Security Posture](11-security-posture.md)
3434
- [CI/CD Templates](12-ci-cd.md)
35+
- [Implementation Guide](13-implementation.md)
3536

3637
## Reference architectures
3738

@@ -41,7 +42,6 @@ Day-2 guides:
4142
## Diagrams
4243

4344
- Mermaid sources: [`/diagrams/mermaid`](../diagrams/mermaid)
44-
- PNG exports: [`/diagrams/png`](../diagrams/png)
4545

4646
## What gets deployed (core)
4747

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ nav:
1717
- Multi-Environment Strategy: 10-multi-env.md
1818
- Security Posture: 11-security-posture.md
1919
- CI/CD Templates: 12-ci-cd.md
20+
- Implementation Guide: 13-implementation.md
2021

2122
theme:
2223
name: readthedocs

0 commit comments

Comments
 (0)