# tsuyakashi/oci-proxmox-node architecture

> Architecture diagram of the GitHub repository tsuyakashi/oci-proxmox-node, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tsuyakashi/oci-proxmox-node
- Repository: https://github.com/tsuyakashi/oci-proxmox-node

## Overview

This repository provisions a standalone Oracle Cloud ARM node running Proxmox VE, then configures it for LXC networking and Tailscale access. The main workflow is: import a Debian 13 ARM image, store credentials and configuration in Vault, apply Terraform, and let cloud-init install and configure Proxmox. The README documents these runtime stages and integrations; only the image-import script was sampled, so Terraform and bootstrap links below rely on the documented workflow and file tree.

Main entry points: [`mod/oci-pve-node/cloud-init/bootstrap.sh.tpl`](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl) (Stage 2 setup), [`mod/oci-pve-node/instance.tf`](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/instance.tf) (OCI instance), [`mod/oci-pve-node/network.tf`](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/network.tf) (OCI network resources), [`env/pve-node/main.tf`](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/env/pve-node/main.tf) (Node environment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_image["Image preparation"]
  node_oci_bucket[("OCI Object Storage")]
  node_image_import["Image importer"]
  node_oci_image["OCI custom image"]
end

subgraph group_provision["Terraform deployment"]
  node_vault[("Vault KV")]
  node_vault_policy["Vault policy setup"]
  node_vault_wrapper["Vault apply wrapper"]
  node_environment["Node environment<br/>[main.tf]"]
  node_network["OCI network resources<br/>[network.tf]"]
  node_instance["OCI instance<br/>[instance.tf]"]
  node_outputs["Deployment outputs<br/>[outputs.tf]"]
end

subgraph group_bootstrap["Host bootstrap"]
  node_cloud_init["Cloud-init bootstrap<br/>[bootstrap.sh.tpl]"]
  node_stage1["Stage 1 setup<br/>[bootstrap.sh.tpl]"]
  node_stage2["Stage 2 setup<br/>[bootstrap.sh.tpl]"]
  node_proxmox["Proxmox VE host<br/>[bootstrap.sh.tpl]"]
  node_zfs["ZFS tank pool<br/>[bootstrap.sh.tpl]"]
end

subgraph group_access["Networking and access"]
  node_container_net["LXC NAT network<br/>[bootstrap.sh.tpl]"]
  node_tailscale["Tailscale connector<br/>[bootstrap.sh.tpl]"]
  node_gui["Proxmox web GUI"]
end

node_operator(("Operator"))
node_debian["Debian ARM image"]
node_tailscale_service["Tailscale network"]
node_game_client(("Valheim traffic"))

node_operator -->|"downloads"| node_debian
node_operator -->|"uploads"| node_oci_bucket
node_oci_bucket -->|"provides image"| node_image_import
node_image_import -->|"imports image"| node_oci_image
node_operator -->|"initializes policy"| node_vault_policy
node_operator -->|"stores config"| node_vault
node_vault_policy -->|"configures access"| node_vault
node_vault -->|"supplies variables"| node_vault_wrapper
node_operator -->|"sources wrapper"| node_vault_wrapper
node_vault_wrapper -->|"provides environment"| node_environment
node_environment -->|"applies resources"| node_network
node_environment -->|"applies resources"| node_instance
node_oci_image -->|"image input"| node_instance
node_network -->|"network attachment"| node_instance
node_instance -->|"runs bootstrap"| node_cloud_init
node_cloud_init -->|"starts"| node_stage1
node_stage1 -->|"reboots into"| node_stage2
node_stage2 -->|"installs"| node_proxmox
node_stage2 -->|"creates pool"| node_zfs
node_stage2 -->|"configures"| node_container_net
node_stage2 -->|"installs and configures"| node_tailscale
node_tailscale -->|"advertises connector"| node_tailscale_service
node_instance -->|"exposes values"| node_outputs
node_tailscale_service -->|"provides private access"| node_gui
node_game_client -.->|"sends UDP traffic"| node_network
node_network -.->|"forwards traffic"| node_container_net

click node_image_import "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/scripts/import-debian-image.py"
click node_vault_policy "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/scripts/vault-policy-init.sh"
click node_vault_wrapper "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/scripts/vault-apply-wrapper.sh"
click node_environment "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/env/pve-node/main.tf"
click node_network "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/network.tf"
click node_instance "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/instance.tf"
click node_outputs "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/outputs.tf"
click node_cloud_init "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl"
click node_stage1 "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl"
click node_stage2 "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl"
click node_proxmox "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl"
click node_zfs "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl"
click node_container_net "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl"
click node_tailscale "https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_oci_bucket,node_image_import,node_oci_image toneBlue
class node_vault,node_vault_policy,node_vault_wrapper,node_environment,node_network,node_instance,node_outputs toneAmber
class node_cloud_init,node_stage1,node_stage2,node_proxmox,node_zfs toneMint
class node_container_net,node_tailscale,node_gui toneRose
class node_operator,node_debian,node_tailscale_service,node_game_client toneIndigo
```

## Components

### Image preparation

- **OCI Object Storage**
- [Image importer](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/scripts/import-debian-image.py): `scripts/import-debian-image.py`
- **OCI custom image**

### Terraform deployment

- **Vault KV**
- [Vault policy setup](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/scripts/vault-policy-init.sh): `scripts/vault-policy-init.sh`
- [Vault apply wrapper](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/scripts/vault-apply-wrapper.sh): `scripts/vault-apply-wrapper.sh`
- [Node environment](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/env/pve-node/main.tf): `env/pve-node/main.tf`
- [OCI network resources](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/network.tf): `mod/oci-pve-node/network.tf`
- [OCI instance](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/instance.tf): `mod/oci-pve-node/instance.tf`
- [Deployment outputs](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/outputs.tf): `mod/oci-pve-node/outputs.tf`

### Host bootstrap

- [Cloud-init bootstrap](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl): `mod/oci-pve-node/cloud-init/bootstrap.sh.tpl`
- [Stage 1 setup](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl): `mod/oci-pve-node/cloud-init/bootstrap.sh.tpl`
- [Stage 2 setup](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl): `mod/oci-pve-node/cloud-init/bootstrap.sh.tpl`
- [Proxmox VE host](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl): `mod/oci-pve-node/cloud-init/bootstrap.sh.tpl`
- [ZFS tank pool](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl): `mod/oci-pve-node/cloud-init/bootstrap.sh.tpl`

### Networking and access

- [LXC NAT network](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl): `mod/oci-pve-node/cloud-init/bootstrap.sh.tpl`
- [Tailscale connector](https://github.com/tsuyakashi/oci-proxmox-node/blob/main/mod/oci-pve-node/cloud-init/bootstrap.sh.tpl): `mod/oci-pve-node/cloud-init/bootstrap.sh.tpl`
- **Proxmox web GUI**

### Other components

- **Operator**
- **Debian ARM image**
- **Tailscale network**
- **Valheim traffic**

## Connections

- Operator → Debian ARM image: downloads
- Operator → OCI Object Storage: uploads
- OCI Object Storage → Image importer: provides image
- Image importer → OCI custom image: imports image
- Operator → Vault policy setup: initializes policy
- Operator → Vault KV: stores config
- Vault policy setup → Vault KV: configures access
- Vault KV → Vault apply wrapper: supplies variables
- Operator → Vault apply wrapper: sources wrapper
- Vault apply wrapper → Node environment: provides environment
- Node environment → OCI network resources: applies resources
- Node environment → OCI instance: applies resources
- OCI custom image → OCI instance: image input
- OCI network resources → OCI instance: network attachment
- OCI instance → Cloud-init bootstrap: runs bootstrap
- Cloud-init bootstrap → Stage 1 setup: starts
- Stage 1 setup → Stage 2 setup: reboots into
- Stage 2 setup → Proxmox VE host: installs
- Stage 2 setup → ZFS tank pool: creates pool
- Stage 2 setup → LXC NAT network: configures
- Stage 2 setup → Tailscale connector: installs and configures
- Tailscale connector → Tailscale network: advertises connector
- OCI instance → Deployment outputs: exposes values
- Tailscale network → Proxmox web GUI: provides private access
- Valheim traffic → OCI network resources: sends UDP traffic
- OCI network resources → LXC NAT network: forwards traffic