diff --git a/.github/workflows/autoupdate-structurizr-diagrams.yml b/.github/workflows/autoupdate-structurizr-diagrams.yml new file mode 100644 index 000000000..68a406acb --- /dev/null +++ b/.github/workflows/autoupdate-structurizr-diagrams.yml @@ -0,0 +1,46 @@ +name: Auto update Structurizr Diagrams + +on: + pull_request: + paths: + - 'docs/workspace.dsl' # This setting will have the action trigger only if certain file changes. Set the location of your DSL. + - '.github/workflows/autoupdate-structurizr-diagrams.yml' # Useful for testing purposes + +jobs: + update-diagrams: + runs-on: ubuntu-latest + container: ghcr.io/sebastienfi/structurizr-cli-with-bonus:latest + steps: + - name: Checkout Repository + uses: actions/checkout@v4 + - name: Set up git + # This step needs to be done before checkout so that the checkout respects clrf + uses: canonical/ubuntu-pro-for-wsl/.github/actions/setup-git@main + with: + token: ${{ secrets.GITHUB_TOKEN }} + - name: Generate Diagram Images + shell: bash + run: | + set -eu + echo "Actual folder is" + echo ${PWD} + /usr/local/structurizr-cli/structurizr.sh export -workspace 'docs/workspace.dsl' -format plantuml -output 'docs/diagrams' + cd 'docs/diagrams' + echo 'Generating PNGs...' + plantuml -tpng *.puml + rm *.puml + - name: Get output branch for branch name + id: get-branch-name + shell: bash + run: echo "branch=${GITHUB_REF#refs/heads/}" >> $GITHUB_OUTPUT + - name: Create Pull Request if there is a diff + uses: peter-evans/create-pull-request@v6 + with: + commit-message: Auto update diagrams + title: 'docs: Auto update diagram files' + labels: docs, automated pr + body: "[Auto-generated pull request](https://github.com/canonical/ubuntu-pro-for-wsl/actions/workflows/autoupdate-structurizr-diagrams.yml) by GitHub Action" + branch: autoupdate-diagrams-${{ steps.get-branch-name.outputs.branch }} + base: ${{ github.head_ref }} + token: ${{ secrets.GITHUB_TOKEN }} + delete-branch: true diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 7cef76e28..0d300a942 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -17,6 +17,8 @@ macOS MSIX powershell PowerShell +structurizr +Structurizr systemd ubuntu UbuntuProForWSL @@ -48,6 +50,7 @@ HIPAA Hostagent LTS os +repo SLA SRU tcp diff --git a/docs/diagrams/readme.md b/docs/diagrams/readme.md new file mode 100644 index 000000000..a9bd70de6 --- /dev/null +++ b/docs/diagrams/readme.md @@ -0,0 +1,18 @@ +Diagrams in this directory are auto-generated. +Any PR that makes changes in the `docs/workspace.dsl` file in this repo will +trigger a GitHub action that updates the diagrams. +This will add a new commit to the PR. + +# Contributing + +If you want to edit the `workspace.dsl` and see your changes reflected during +testing you have two options: + +1. The [online editor](https://structurizr.com/dsl) from Structurizr +2. The [CLI](https://docs.structurizr.com/cli) from Structurizr + +The diagrams are built according to the [C4 model](https://c4model.com/). +This allows architectural diagrams to be constructed at different levels of abstraction from a single `workspace.dsl`. + +If contributing to the diagrams you should be familiar with the C4 Model. +Any change you make could potentially impact multiple diagrams. diff --git a/docs/diagrams/structurizr-ContainerComponents-key.png b/docs/diagrams/structurizr-ContainerComponents-key.png new file mode 100644 index 000000000..45e7dea23 Binary files /dev/null and b/docs/diagrams/structurizr-ContainerComponents-key.png differ diff --git a/docs/diagrams/structurizr-ContainerComponents.png b/docs/diagrams/structurizr-ContainerComponents.png new file mode 100644 index 000000000..608428b3f Binary files /dev/null and b/docs/diagrams/structurizr-ContainerComponents.png differ diff --git a/docs/diagrams/structurizr-SystemContainers-key.png b/docs/diagrams/structurizr-SystemContainers-key.png new file mode 100644 index 000000000..d9a977eda Binary files /dev/null and b/docs/diagrams/structurizr-SystemContainers-key.png differ diff --git a/docs/diagrams/structurizr-SystemContainers.png b/docs/diagrams/structurizr-SystemContainers.png new file mode 100644 index 000000000..f6ed076b4 Binary files /dev/null and b/docs/diagrams/structurizr-SystemContainers.png differ diff --git a/docs/diagrams/structurizr-SystemContext-key.png b/docs/diagrams/structurizr-SystemContext-key.png new file mode 100644 index 000000000..e91925cb1 Binary files /dev/null and b/docs/diagrams/structurizr-SystemContext-key.png differ diff --git a/docs/diagrams/structurizr-SystemContext.png b/docs/diagrams/structurizr-SystemContext.png new file mode 100644 index 000000000..73705ce73 Binary files /dev/null and b/docs/diagrams/structurizr-SystemContext.png differ diff --git a/docs/diagrams/structurizr-SystemLandscape-key.png b/docs/diagrams/structurizr-SystemLandscape-key.png new file mode 100644 index 000000000..e91925cb1 Binary files /dev/null and b/docs/diagrams/structurizr-SystemLandscape-key.png differ diff --git a/docs/diagrams/structurizr-SystemLandscape.png b/docs/diagrams/structurizr-SystemLandscape.png new file mode 100644 index 000000000..f3903c285 Binary files /dev/null and b/docs/diagrams/structurizr-SystemLandscape.png differ diff --git a/docs/diagrams/structurizr-UP4WTutorial-key.png b/docs/diagrams/structurizr-UP4WTutorial-key.png new file mode 100644 index 000000000..d92a5c6a6 Binary files /dev/null and b/docs/diagrams/structurizr-UP4WTutorial-key.png differ diff --git a/docs/diagrams/structurizr-UP4WTutorial.png b/docs/diagrams/structurizr-UP4WTutorial.png new file mode 100644 index 000000000..2eb8cd853 Binary files /dev/null and b/docs/diagrams/structurizr-UP4WTutorial.png differ diff --git a/docs/diagrams/structurizr-UbuntuProForWSL-key.png b/docs/diagrams/structurizr-UbuntuProForWSL-key.png new file mode 100644 index 000000000..d92a5c6a6 Binary files /dev/null and b/docs/diagrams/structurizr-UbuntuProForWSL-key.png differ diff --git a/docs/diagrams/structurizr-UbuntuProForWSL.png b/docs/diagrams/structurizr-UbuntuProForWSL.png new file mode 100644 index 000000000..e84a9c2d5 Binary files /dev/null and b/docs/diagrams/structurizr-UbuntuProForWSL.png differ diff --git a/docs/workspace.dsl b/docs/workspace.dsl new file mode 100644 index 000000000..6681973a7 --- /dev/null +++ b/docs/workspace.dsl @@ -0,0 +1,189 @@ +workspace { + + model { + + # Enable nested groups: "" "Existing" + properties { "" "Existing" + "structurizr.groupSeparator" "/" + } + # People and software systems + up4w = softwareSystem "UP4W " { + up4wagent = container "UP4W Windows Agent" { + configModule = component "Configuration Module" + landscapeProService = component "Landscape Pro Service" + } + up4wgui = container "UP4W Windows GUI" + } + wslProService = softwareSystem "WSL Pro Service" + + # group "Ubuntu Pro offering for Ubuntu WSL" { + canonical = person "Canonical Support Line" "24/7 enterprise support for Ubuntu and your full open source stack" "Existing" + landscape = softwareSystem "Landscape" "Included with your Ubuntu Pro subscription. Automates security patching, auditing, access management and compliance tasks across your Ubuntu estate." "Existing, Service" + upc = softwareSystem "Ubuntu Pro" "Automates the enablement of Ubuntu Pro services" "Existing" + # esm = softwareSystem "Canonical ESM" "1,800+ additional high and critical patches, 10 years of maintenance for the whole stack" "Existing" + # cis = softwareSystem "CIS" "Automates compliance and auditing with the Center for Internet Security (CIS) benchmarks" "Existing" + # } + landscapeClient = softwareSystem "Landscape Client" "" "Existing" + landscapeServer = softwareSystem "Landscape Server" "" "Existing" + proClient = softwareSystem "Ubuntu Pro Client" "" "Existing" + user = person "User" + windowsRegistry = softwareSystem "Windows registry" "" "Existing" + ups = softwareSystem "Ubuntu Pro subscription" "" "Existing, Service" + # wsl = softwareSystem "WSL" "" "Existing" + + + # Relationships + configModule -> landscapeProService "Configures" + configModule -> windowsRegistry "Reads configuration from" + configModule -> wslProService "Sends configuration to" + landscapeServer -> landscapeClient "Reads from and sends instructions to" + landscapeServer -> landscapeProService "Reads from and sends instructions to" + up4w -> canonical "Enables 24/7 optional enterprise-grade support from" + up4w -> landscape "Registers your Windows host and Ubuntu WSL instances with" + up4w -> ups "Adds your Ubuntu WSL instances to your" + up4w -> upc "Attaches to Ubuntu Pro" + up4wgui -> up4wagent "Writes configuration to" + user -> up4w "Uses" + wslProService -> landscapeClient "Configures" + wslProService -> proClient "Configures" + # landscapeClient -> landscapeServer "Distro information + # landscapeProService -> landscapeClient "Executes commands" + # landscapeProService -> landscapeServer "Connects to, sends information to, and receives commands from"" + # landscapeProService -> landscapeServer "System and WSL information" + # landscapeProService -> wsl "Starts and stops Ubuntu WSL instances created by" + # landscapeServer -> landscapeClient "Distro management commands" + # landscapeServer -> landscapeProService "Lifetime management commands" + # upc -> cis "Automates compliance and auditing" + # upc -> esm "Enables stability, security, and compliance with" + + + deploymentEnvironment "UP4WTutorial" { + g1 = deploymentGroup "1" + g2 = deploymentGroup "2" + g3 = deploymentGroup "3" + g4 = deploymentGroup "4" + + + + deploymentNode "Your computer = Windows host" "" "Windows" { + softwareSystemInstance windowsRegistry g1 + + deploymentNode "Ubuntu WSL instance (Ubuntu 22.04 LTS)" { + softwareSystemInstance landscapeServer g1,g2 + } + + group "UP4W appx" { + containerInstance up4wgui g1 + containerInstance up4wagent g1,g2 + } + + deploymentNode "Ubuntu WSL instance (Ubuntu Preview; created locally)" { + softwareSystemInstance wslProService g1 + softwareSystemInstance proClient g1 + softwareSystemInstance landscapeClient g1 + + } + + deploymentNode "Ubuntu WSL instance (Ubuntu; created remotely via Landscape Server)" { + softwareSystemInstance wslProService g2 + softwareSystemInstance proClient g2 + softwareSystemInstance landscapeClient g2 + + } + + } + } + + + + deploymentEnvironment "UbuntuProForWSL" { + deploymentNode "Your computer = Windows host" "" "Windows" { + group "UP4W appx" { + containerInstance up4wgui + containerInstance up4wagent + } + softwareSystemInstance windowsRegistry + # softwareSystemInstance WSL + deploymentNode "WSL (VM)" "" "" { + deploymentNode "Ubuntu WSL instance (distro)" "" "Ubuntu (Preview)" { + softwareSystemInstance wslProService + softwareSystemInstance proClient + softwareSystemInstance landscapeClient + } + + } + } + deploymentNode "Someone else's computer" "" "" { + softwareSystemInstance landscapeServer + } + } + + } + + views { + systemLandscape "SystemLandscape" { + include user up4w landscape ups + autoLayout + } + systemContext up4w "SystemContext" { + include user up4w landscape ups + autoLayout + } + + container up4w "SystemContainers" { + include * + autoLayout + } + component up4wagent "ContainerComponents" { + include * + autoLayout + } + + deployment up4w "UbuntuProForWSL" "UbuntuProForWSL" { + include * + autoLayout + properties { + "structurizr.groups" true + } + } + + deployment up4w "UP4WTutorial" "UP4WTutorial" { + include * + # autoLayout + properties { + "structurizr.groups" true + } + } + + theme default + + styles { + element "Element" { + metadata false + fontSize 25 + } + # element "Software System" { + # metadata false + # background #1168bd + # color #ffffff + # } + element "Person" { + metadata false + shape person + # background red + color #ffffff + } + element "Existing" { + background #999999 + color #ffffff + } + + element "Service" { + background #999999 + color #ffffff + shape Box + } + } + } + +}