Skip to content

Commit dcf1cf4

Browse files
icklersicklers
authored
Initialize Tutorial (#2)
* Initialize Tutorial * Deploy to GH Pages
1 parent 0f2dd7d commit dcf1cf4

62 files changed

Lines changed: 3820 additions & 21 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gemini/settings.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"mcpServers": {
3+
"memory": {
4+
"command": "docker",
5+
"args": [
6+
"run",
7+
"-i",
8+
"-v",
9+
"/home/si/dev/crossplane-demo/.memory:/data",
10+
"-e",
11+
"MEMORY_FILE_PATH=/data/memory.json",
12+
"--rm",
13+
"mcp/memory"
14+
]
15+
},
16+
"kubernetes": {
17+
"command": "docker",
18+
"args": [
19+
"run",
20+
"-i",
21+
"--rm",
22+
"mcp/kubernetes"
23+
]
24+
}
25+
}
26+
}

‎.github/workflows/deploy-gh-pages.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Deploy MkDocs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: write
11+
pages: write
12+
id-token: write
13+
14+
jobs:
15+
deploy:
16+
runs-on: ubuntu-latest
17+
18+
steps:
19+
- name: Checkout repository
20+
uses: actions/checkout@v4
21+
with:
22+
fetch-depth: 0 # Fetch full history for git info
23+
24+
- name: Install uv
25+
uses: astral-sh/setup-uv@v3
26+
with:
27+
enable-cache: true
28+
cache-dependency-glob: "pyproject.toml"
29+
30+
- name: Set up Python
31+
run: uv python install 3.13
32+
33+
- name: Cache uv dependencies
34+
uses: actions/cache@v4
35+
with:
36+
path: |
37+
~/.cache/uv
38+
.venv
39+
key: uv-${{ runner.os }}-${{ hashFiles('pyproject.toml', 'uv.lock') }}
40+
restore-keys: |
41+
uv-${{ runner.os }}-
42+
43+
- name: Install dependencies
44+
run: uv sync
45+
46+
- name: Configure Git
47+
run: |
48+
git config --global user.name "github-actions[bot]"
49+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
50+
51+
- name: Deploy to GitHub Pages
52+
run: uv run mkdocs gh-deploy --force

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.idea
2+
3+
# Devbox
4+
5+
.devbox
6+
devbox.lock
7+
8+
# Python
9+
.venv

‎.memory/memory.json‎

Whitespace-only changes.

‎.vscode/mcp.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"servers": {
3+
"memory": {
4+
"command": "docker",
5+
"args": [
6+
"run",
7+
"-i",
8+
"-v",
9+
"/home/user/idp-tutorial/.memory:/data",
10+
"-e",
11+
"MEMORY_FILE_PATH=/data/memory.json",
12+
"--rm",
13+
"mcp/memory"
14+
]
15+
},
16+
"kubernetes": {
17+
"command": "docker",
18+
"args": [
19+
"run",
20+
"-i",
21+
"--rm",
22+
"mcp/kubernetes"
23+
]
24+
}
25+
}
26+
}

‎LICENSE‎

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
1-
MIT License
2-
3-
Copyright (c) 2025 Sebastian Ickler
4-
5-
Permission is hereby granted, free of charge, to any person obtaining a copy
6-
of this software and associated documentation files (the "Software"), to deal
7-
in the Software without restriction, including without limitation the rights
8-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9-
copies of the Software, and to permit persons to whom the Software is
10-
furnished to do so, subject to the following conditions:
11-
12-
The above copyright notice and this permission notice shall be included in all
13-
copies or substantial portions of the Software.
14-
15-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21-
SOFTWARE.
1+
MIT License
2+
3+
Copyright (c) 2025 Sebastian Ickler
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# IDP Tutorial: Building a Production-Ready Platform with Crossplane and ArgoCD
2+
3+
Welcome to the Internal Developer Platform (IDP) tutorial. This repository contains a complete, hands-on guide to building a production-ready, multi-cloud platform using Crossplane for infrastructure-as-code and ArgoCD for GitOps delivery.
4+
5+
This project is designed for Senior DevOps Engineers who are already comfortable with Kubernetes and want to master the art of platform engineering.
6+
7+
## Full Documentation
8+
9+
The complete, detailed documentation for this tutorial is generated by MkDocs and can be found in the `/docs` directory.
10+
11+
**➡️ [Next Section: Repository Management](./docs/repository-management/01-multi-repo-strategy.md)**
12+
13+
## Prerequisites
14+
15+
Before you begin, ensure you have the following:
16+
17+
- A GitHub account.
18+
- Access to an Azure, GCP, or Hetzner cloud account (optional, but required for provider-specific exercises).
19+
- [Nix](https://nixos.org/download.html) and [Devbox](https://www.jetpack.io/devbox/docs/installing-devbox/) installed on your local machine (Linux or macOS).
20+
21+
For detailed setup instructions, please see the **[Getting Started Guide](./docs/getting-started/01-introduction.md)**.
22+
23+
## VS Code Configuration (Important)
24+
25+
This repository contains configuration for the Gemini Code Assist extension in the `.vscode/mcp.json` file. This allows the assistant to have long-term memory about our project.
26+
27+
After you clone this repository, you **must** update the `mcp.json` file to point to the absolute path of the `.memory` directory on your local machine.
28+
29+
1. Open `.vscode/mcp.json`.
30+
2. Find the line containing `e:\Dev\idp-tutorial\.memory:/data`.
31+
3. Replace `e:\Dev\idp-tutorial` with the absolute path to where you have cloned this repository.
32+
33+
**Example:** If you cloned the repository to `/home/user/projects/idp-tutorial`, the new line should be `"-v", "/home/user/projects/idp-tutorial/.memory:/data",`.
34+
35+
## Quick Start: Bootstrapping the Environment
36+
37+
These steps will get your local learning environment up and running.
38+
39+
### 1. Create Your Platform GitOps Repository
40+
41+
This tutorial provides the content for your "Platform GitOps Repo". You will create a new GitHub repository and push this content to it.
42+
43+
1. **Clone this tutorial repository** to your local machine:
44+
45+
```bash
46+
gh repo clone icklers/idp-tutorial
47+
cd idp-tutorial
48+
```
49+
50+
2. **Create your new Platform GitOps Repo on GitHub** and push the content. This command will create a new public repository on GitHub (e.g., `my-platform-gitops-repo`), push the current directory's content to it, and set it as the `origin` remote.
51+
52+
```bash
53+
# Replace <your-repo-name> with your desired repository name (e.g., my-platform-gitops-repo)
54+
gh repo create <your-repo-name> --public --source . --remote origin
55+
```
56+
57+
This repository (`<your-repo-name>`) will now be your source of truth for all GitOps configurations.
58+
59+
### 2. Activate the Development Environment
60+
61+
This command uses Nix and Devbox to install the exact versions of all the tools required for this tutorial.
62+
63+
```bash
64+
devbox shell
65+
```
66+
67+
### 3. Install Project Tools
68+
69+
Run the `setup-tools` script to install the Crossplane CLI and Python dependencies for MkDocs:
70+
71+
```bash
72+
devbox run setup-tools
73+
```
74+
75+
### 4. Create the Local Kubernetes Cluster
76+
77+
This command creates a local Kubernetes-in-Docker (KinD) cluster that will serve as our platform's control plane.
78+
79+
```bash
80+
kind create cluster --config gitops-bootstrap/kind-cluster/kind-cluster.yaml
81+
```
82+
83+
### 5. Bootstrap ArgoCD
84+
85+
This is the only manual step. First, we create the namespace for ArgoCD. Then, we apply the official installation manifest directly from the ArgoCD project's GitHub repository. This is the recommended way to ensure you are installing a stable and complete version of ArgoCD.
86+
87+
Finally, we apply our `platform-core.yaml` to tell our new ArgoCD instance to start managing our platform from Git.
88+
89+
```bash
90+
# Create the namespace for ArgoCD
91+
kubectl create namespace argocd
92+
93+
# Apply the official ArgoCD installation manifest
94+
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
95+
96+
# The platform-core.yaml manifest needs to point to your new GitOps repository.
97+
# Set your repository URL as an environment variable and use `sed` to update the file.
98+
export PLATFORM_GITOPS_REPO_URL="https://github.com/your-username/your-repo-name.git" # <-- REPLACE THIS
99+
sed -i "s|__YOUR_PLATFORM_GITOPS_REPO_URL__|$PLATFORM_GITOPS_REPO_URL|g" gitops-bootstrap/argocd/platform-core.yaml
100+
101+
# Apply the Platform Core ApplicationSet to start the GitOps sync
102+
kubectl apply -f gitops-bootstrap/argocd/platform-core.yaml
103+
```
104+
105+
### 6. Access ArgoCD
106+
107+
Your entire platform is now being created via GitOps. You can watch it happen in the ArgoCD UI.
108+
109+
```bash
110+
# Get the initial admin password
111+
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo
112+
113+
# Port-forward the ArgoCD server
114+
kubectl port-forward svc/argocd-server -n argocd 8080:443
115+
```
116+
117+
You can now log in to `https://localhost:8080` with username `admin` and the password you just retrieved.
118+
119+
## Next Steps
120+
121+
Your environment is now fully bootstrapped. To understand what you've built and how to use your new platform, please proceed to the **[full tutorial documentation](./docs/index.md)**.

‎devbox.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"packages": [
3+
"argocd@latest",
4+
"oh-my-zsh@latest",
5+
"zsh@latest",
6+
"kubectl@latest",
7+
"gh@latest",
8+
"uv@latest"
9+
],
10+
"shell": {
11+
"init_hook": [
12+
"[ ! -d .venv ] && uv venv",
13+
"source .venv/bin/activate",
14+
"export UV_LINK_MODE=copy",
15+
"echo 'Welcome to the GitOps Tutorial Dev Environment!'"
16+
],
17+
"scripts": {
18+
"setup-tools": [
19+
"mkdir -p ~/bin/",
20+
"uv pip install -r pyproject.toml",
21+
"[ ! -e ~/bin/crossplane ] && curl -sL \"https://raw.githubusercontent.com/crossplane/crossplane/main/install.sh\" | sh > /dev/null",
22+
"mv crossplane ~/bin/ && chmod +x ~/bin/crossplane",
23+
"[ ! -e ~/bin/argocd ] && curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64 && mv argocd-linux-amd64 ~/bin/argocd && chmod +x ~/bin/argocd",
24+
"echo 'export PATH=~/bin:$PATH' >> ~/.profile",
25+
"source ~/.profile",
26+
"echo \"Crossplane:\" $(crossplane version --client)",
27+
"echo $(argocd version --client | head -1)"
28+
]
29+
}
30+
}
31+
}

‎docs/.nav.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
nav:
2+
- 'Introduction': 'index.md'
3+
- 'Getting Started': 'getting-started/'
4+
# - 'Repository Management': 'repository-management/'
5+
# - 'GitOps Fundamentals': 'gitops-fundamentals/'
6+
# - 'Providers': 'providers/'
7+
# - 'Security': 'security/'
8+
# - 'Observability': 'observability/'
9+
# - 'Advanced Topics': 'advanced/'
10+
# - 'Troubleshooting': 'troubleshooting.md'
11+
12+
flatten_single_child_sections: true

‎docs/advanced/.nav.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
nav:
2+
- 01-composition-functions.md
3+
- 02-multi-cluster-management.md

0 commit comments

Comments
 (0)