# mchmarny/custom-cloud-workstation-image architecture

> Architecture diagram of the GitHub repository mchmarny/custom-cloud-workstation-image, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mchmarny/custom-cloud-workstation-image
- Repository: https://github.com/mchmarny/custom-cloud-workstation-image

## Overview

##### Main Components
- Git Repository & File Structure – Represent the repository which holds source files including configuration scripts (in assets/), the Dockerfile, version file, Makefile, and cloudbuild.yaml. These components define both the container image build and startup configuration (e.g., SSH daemon settings, VS Code user settings, and git configuration).
- CI/CD Pipeline – Highlight Cloud Build as the central pipeline that reads cloudbuild.yaml to trigger builds. Indicate that new builds are triggered either manually (via git tag pushes) or on a scheduled basis using Cloud Scheduler.
- Artifact Registry – Show the container image repository where the newly built Docker images are published.
- Cloud Workstations Cluster & Configuration – Represent the Cloud Workstations cluster that gets created/updated using the custom image. Include the separate steps of cluster creation, configuration update (which uses the new container image and service accounts), and workstation instance creation.
- External GCP Services – Incorporate Google Cloud IAM (service account management and permissions), Cloud Build triggers, and Cloud Scheduler for the scheduled image rebuilds.

##### Relationships and Data Flow
- The code repository (with Dockerfile, assets, and setup scripts) is committed and tagged by developers. A git tag triggers the Cloud Build pipeline.
- Cloud Build then invokes the build process, using the Dockerfile to package the image and then pushes it to the Artifact Registry.
- Once a new image is published, the Cloud Workstations configuration is automatically updated—this update includes pulling in the proper image digest.
- On a daily or manual schedule, Cloud Scheduler triggers a new build cycle to ensure the image is up to date.
- The updated image is then used by Cloud Workstations to launch workstations, which run the preconfigured environment (with settings for Go and VS Code).

##### Architectural Patterns & Design Principles
- Separation of Concerns – The build process is separated from deployment. Dockerfile and assets handle setup specifics while cloudbuild.yaml manages the build pipeline.
- Automation & Idempotency – The design emphasizes automatic image builds (via git tag and scheduled triggers) and user configuration scripts (in assets/setup) which are idempotent, ensuring consistency even if applied multiple times.
- Integration with GCP Services – The project heavily integrates with Google Cloud services (Cloud Build, Artifact Registry, Cloud Workstations, Cloud Scheduler, and IAM) to offer a seamless automated development environment.

##### Relevant Technologies & Frameworks
- Containerization using Docker (the Dockerfile and associated assets)
- Google Cloud Build for CI/CD
- Google Artifact Registry for container image storage
- Google Cloud Workstations for the final deployment of the customized environment
- Google Cloud Scheduler for periodically triggering the image rebuild process

- Additional Details: Optionally denote service accounts, IAM roles, and specific configuration scripts (e.g., SSH setup scripts in assets/etc and user config scripts in assets/setup) to highlight customization points.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Repository Subgraph
    subgraph "Source Repository"
        repoDocker["Dockerfile"]:::component
        repoCloudbuild["cloudbuild.yaml"]:::component
        repoAssets["assets/"]:::component
        subgraph "Configuration Scripts"
            etcSSH["sshd_config"]:::script
            startupDir["workstation-startup.d/"]:::script
            addUser["010_add-user.sh"]:::script
            startSSHD["020_start-sshd.sh"]:::script
            assetsSetup["assets/setup/"]:::script
            setupCode["assets/setup/code"]:::script
            setupGit["assets/setup/git"]:::script
            setupSettings["settings.json"]:::script
            entrypoint["entrypoint.sh"]:::script
        end
    end

    %% Main Pipeline Flow
    gitTag["GitTag"]:::trigger --> repoCloudbuild
    repoDocker --- repoCloudbuild
    repoAssets --- repoCloudbuild

    repoCloudbuild -->|"triggers"| ciCd["CI/CD Pipeline (Cloud Build)"]:::build
    ciCd -->|"builds"| artifact["Artifact Registry"]:::artifact
    artifact -->|"updates"| workstations["Cloud Workstations Cluster/Configuration"]:::workstation
    cloudScheduler["Cloud Scheduler"]:::scheduler -->|"schedules"| ciCd
    gcpIAM["Google Cloud IAM"]:::iam -->|"provides-perms"| workstations

    %% Linking configuration scripts to Cloud Workstations configuration
    assetsSetup --- workstations
    entrypoint --- workstations
    etcSSH --- workstations
    startupDir --- workstations
    addUser --- startupDir
    startSSHD --- startupDir
    setupCode --- assetsSetup
    setupGit --- assetsSetup
    setupSettings --- assetsSetup

    %% Styles
    classDef repo fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef build fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef artifact fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef workstation fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef scheduler fill:#D8BFD8,stroke:#000,stroke-width:1px;
    classDef iam fill:#FFC0CB,stroke:#000,stroke-width:1px;
    classDef script fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef trigger fill:#FFD700,stroke:#000,stroke-width:1px;

    %% Click Events
    click repoDocker "https://github.com/mchmarny/custom-cloud-workstation-image/tree/main/Dockerfile"
    click repoCloudbuild "https://github.com/mchmarny/custom-cloud-workstation-image/blob/main/cloudbuild.yaml"
    click repoAssets "https://github.com/mchmarny/custom-cloud-workstation-image/tree/main/assets/"
    click etcSSH "https://github.com/mchmarny/custom-cloud-workstation-image/tree/main/assets/etc/ssh/sshd_config"
    click startupDir "https://github.com/mchmarny/custom-cloud-workstation-image/tree/main/assets/etc/workstation-startup.d/"
    click addUser "https://github.com/mchmarny/custom-cloud-workstation-image/blob/main/assets/etc/workstation-startup.d/010_add-user.sh"
    click startSSHD "https://github.com/mchmarny/custom-cloud-workstation-image/blob/main/assets/etc/workstation-startup.d/020_start-sshd.sh"
    click assetsSetup "https://github.com/mchmarny/custom-cloud-workstation-image/tree/main/assets/setup/"
    click setupCode "https://github.com/mchmarny/custom-cloud-workstation-image/tree/main/assets/setup/code"
    click setupGit "https://github.com/mchmarny/custom-cloud-workstation-image/tree/main/assets/setup/git"
    click setupSettings "https://github.com/mchmarny/custom-cloud-workstation-image/blob/main/assets/setup/profile/settings.json"
    click entrypoint "https://github.com/mchmarny/custom-cloud-workstation-image/blob/main/assets/google/scripts/entrypoint.sh"
    click ciCd "https://github.com/mchmarny/custom-cloud-workstation-image/blob/main/cloudbuild.yaml"
```
