diff --git a/.hatch/requirements-docs.txt b/.hatch/requirements-docs.txt index cebd1e3c16..d8350ffbe4 100644 --- a/.hatch/requirements-docs.txt +++ b/.hatch/requirements-docs.txt @@ -1,17 +1,125 @@ # # This file is autogenerated by hatch-pip-compile with Python 3.12 # +# - appdirs==1.4.4 +# - azure-core==1.32.0 +# - azure-identity==1.19.0 +# - azure-keyvault-certificates==4.9.0 +# - azure-keyvault-keys==4.10.0 +# - azure-keyvault-secrets==4.9.0 +# - azure-mgmt-compute==33.0.0 +# - azure-mgmt-containerinstance==10.1.0 +# - azure-mgmt-dns==8.2.0 +# - azure-mgmt-keyvault==10.3.1 +# - azure-mgmt-msi==7.0.0 +# - azure-mgmt-rdbms==10.1.0 +# - azure-mgmt-resource==23.2.0 +# - azure-mgmt-storage==21.2.1 +# - azure-storage-blob==12.24.0 +# - azure-storage-file-datalake==12.18.0 +# - azure-storage-file-share==12.20.0 +# - chevron==0.14.0 +# - cryptography==44.0.0 +# - fqdn==1.5.1 +# - psycopg[binary]==3.1.19 +# - pulumi-azure-native==2.74.0 +# - pulumi-azuread==6.0.1 +# - pulumi-random==4.16.7 +# - pulumi==3.142.0 +# - pydantic==2.10.2 +# - pyjwt[crypto]==2.10.1 +# - pytz==2024.2 +# - pyyaml==6.0.2 +# - rich==13.9.4 +# - simple-acme-dns==3.2.0 +# - typer==0.14.0 +# - websocket-client==1.8.0 # - emoji==2.14.0 # - myst-parser==4.0.0 # - pydata-sphinx-theme==0.16.0 # - sphinx-togglebutton==0.3.2 # - sphinx==8.1.3 +# - sphinxcontrib-typer==0.5.1 # accessible-pygments==0.0.5 # via pydata-sphinx-theme +acme==2.10.0 + # via simple-acme-dns alabaster==1.0.0 # via sphinx +annotated-types==0.7.0 + # via pydantic +appdirs==1.4.4 + # via hatch.envs.docs +arpeggio==2.0.2 + # via parver +attrs==24.2.0 + # via parver +azure-common==1.1.28 + # via + # azure-mgmt-compute + # azure-mgmt-containerinstance + # azure-mgmt-dns + # azure-mgmt-keyvault + # azure-mgmt-msi + # azure-mgmt-rdbms + # azure-mgmt-resource + # azure-mgmt-storage +azure-core==1.32.0 + # via + # hatch.envs.docs + # azure-identity + # azure-keyvault-certificates + # azure-keyvault-keys + # azure-keyvault-secrets + # azure-mgmt-core + # azure-storage-blob + # azure-storage-file-datalake + # azure-storage-file-share + # msrest +azure-identity==1.19.0 + # via hatch.envs.docs +azure-keyvault-certificates==4.9.0 + # via hatch.envs.docs +azure-keyvault-keys==4.10.0 + # via hatch.envs.docs +azure-keyvault-secrets==4.9.0 + # via hatch.envs.docs +azure-mgmt-compute==33.0.0 + # via hatch.envs.docs +azure-mgmt-containerinstance==10.1.0 + # via hatch.envs.docs +azure-mgmt-core==1.5.0 + # via + # azure-mgmt-compute + # azure-mgmt-containerinstance + # azure-mgmt-dns + # azure-mgmt-keyvault + # azure-mgmt-msi + # azure-mgmt-rdbms + # azure-mgmt-resource + # azure-mgmt-storage +azure-mgmt-dns==8.2.0 + # via hatch.envs.docs +azure-mgmt-keyvault==10.3.1 + # via hatch.envs.docs +azure-mgmt-msi==7.0.0 + # via hatch.envs.docs +azure-mgmt-rdbms==10.1.0 + # via hatch.envs.docs +azure-mgmt-resource==23.2.0 + # via hatch.envs.docs +azure-mgmt-storage==21.2.1 + # via hatch.envs.docs +azure-storage-blob==12.24.0 + # via + # hatch.envs.docs + # azure-storage-file-datalake +azure-storage-file-datalake==12.18.0 + # via hatch.envs.docs +azure-storage-file-share==12.20.0 + # via hatch.envs.docs babel==2.16.0 # via # pydata-sphinx-theme @@ -19,9 +127,37 @@ babel==2.16.0 beautifulsoup4==4.12.3 # via pydata-sphinx-theme certifi==2024.8.30 - # via requests + # via + # msrest + # requests +cffi==1.17.1 + # via cryptography charset-normalizer==3.4.0 # via requests +chevron==0.14.0 + # via hatch.envs.docs +click==8.1.7 + # via + # typer + # typer-slim +cryptography==44.0.0 + # via + # hatch.envs.docs + # acme + # azure-identity + # azure-keyvault-keys + # azure-storage-blob + # azure-storage-file-share + # josepy + # msal + # pyjwt + # pyopenssl +debugpy==1.8.9 + # via pulumi +dill==0.3.9 + # via pulumi +dnspython==2.7.0 + # via simple-acme-dns docutils==0.21.2 # via # myst-parser @@ -30,39 +166,151 @@ docutils==0.21.2 # sphinx-togglebutton emoji==2.14.0 # via hatch.envs.docs +fqdn==1.5.1 + # via hatch.envs.docs +grpcio==1.66.2 + # via pulumi idna==3.10 # via requests imagesize==1.4.1 # via sphinx +isodate==0.7.2 + # via + # azure-keyvault-certificates + # azure-keyvault-keys + # azure-keyvault-secrets + # azure-mgmt-compute + # azure-mgmt-containerinstance + # azure-mgmt-dns + # azure-mgmt-keyvault + # azure-mgmt-resource + # azure-mgmt-storage + # azure-storage-blob + # azure-storage-file-datalake + # azure-storage-file-share + # msrest jinja2==3.1.4 # via # myst-parser # sphinx +josepy==1.14.0 + # via acme markdown-it-py==3.0.0 # via # mdit-py-plugins # myst-parser + # rich markupsafe==3.0.2 # via jinja2 mdit-py-plugins==0.4.2 # via myst-parser mdurl==0.1.2 # via markdown-it-py +msal==1.31.1 + # via + # azure-identity + # msal-extensions +msal-extensions==1.2.0 + # via azure-identity +msrest==0.7.1 + # via + # azure-mgmt-msi + # azure-mgmt-rdbms myst-parser==4.0.0 # via hatch.envs.docs +oauthlib==3.2.2 + # via requests-oauthlib packaging==24.2 # via sphinx +parver==0.5 + # via + # pulumi-azure-native + # pulumi-azuread + # pulumi-random +portalocker==2.10.1 + # via msal-extensions +protobuf==4.25.5 + # via pulumi +psycopg==3.1.19 + # via hatch.envs.docs +psycopg-binary==3.1.19 + # via psycopg +pulumi==3.142.0 + # via + # hatch.envs.docs + # pulumi-azure-native + # pulumi-azuread + # pulumi-random +pulumi-azure-native==2.74.0 + # via hatch.envs.docs +pulumi-azuread==6.0.1 + # via hatch.envs.docs +pulumi-random==4.16.7 + # via hatch.envs.docs +pycparser==2.22 + # via cffi +pydantic==2.10.2 + # via hatch.envs.docs +pydantic-core==2.27.1 + # via pydantic pydata-sphinx-theme==0.16.0 # via hatch.envs.docs pygments==2.18.0 # via # accessible-pygments # pydata-sphinx-theme + # rich # sphinx +pyjwt==2.10.1 + # via + # hatch.envs.docs + # msal +pyopenssl==24.3.0 + # via + # acme + # josepy +pyrfc3339==2.0.1 + # via acme +pytz==2024.2 + # via + # hatch.envs.docs + # acme pyyaml==6.0.2 - # via myst-parser + # via + # hatch.envs.docs + # myst-parser + # pulumi requests==2.32.3 - # via sphinx + # via + # acme + # azure-core + # msal + # msrest + # requests-oauthlib + # sphinx +requests-oauthlib==2.0.0 + # via msrest +rich==13.9.4 + # via + # hatch.envs.docs + # typer + # typer-slim +semver==2.13.0 + # via + # pulumi + # pulumi-azure-native + # pulumi-azuread + # pulumi-random +shellingham==1.5.4 + # via + # typer + # typer-slim +simple-acme-dns==3.2.0 + # via hatch.envs.docs +six==1.16.0 + # via + # azure-core + # pulumi snowballstemmer==2.2.0 # via sphinx soupsieve==2.6 @@ -73,6 +321,7 @@ sphinx==8.1.3 # myst-parser # pydata-sphinx-theme # sphinx-togglebutton + # sphinxcontrib-typer sphinx-togglebutton==0.3.2 # via hatch.envs.docs sphinxcontrib-applehelp==2.0.0 @@ -87,10 +336,38 @@ sphinxcontrib-qthelp==2.0.0 # via sphinx sphinxcontrib-serializinghtml==2.0.0 # via sphinx +sphinxcontrib-typer==0.5.1 + # via hatch.envs.docs +typer==0.14.0 + # via hatch.envs.docs +typer-slim==0.14.0 + # via sphinxcontrib-typer typing-extensions==4.12.2 - # via pydata-sphinx-theme + # via + # azure-core + # azure-identity + # azure-keyvault-certificates + # azure-keyvault-keys + # azure-keyvault-secrets + # azure-mgmt-compute + # azure-mgmt-dns + # azure-mgmt-keyvault + # azure-mgmt-resource + # azure-storage-blob + # azure-storage-file-datalake + # azure-storage-file-share + # psycopg + # pydantic + # pydantic-core + # pydata-sphinx-theme + # typer + # typer-slim urllib3==2.2.3 # via requests +validators==0.34.0 + # via simple-acme-dns +websocket-client==1.8.0 + # via hatch.envs.docs wheel==0.45.1 # via sphinx-togglebutton diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 145d005f83..56f8f2b24f 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -16,6 +16,8 @@ formats: python: install: - requirements: .hatch/requirements-docs.txt + - method: pip + path: . sphinx: configuration: docs/source/conf.py diff --git a/docs/source/conf.py b/docs/source/conf.py index f262d36dc2..a1e2c34385 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -55,6 +55,7 @@ extensions = [ "myst_parser", "sphinx_togglebutton", + "sphinxcontrib.typer", ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/source/deployment/deploy_shm.md b/docs/source/deployment/deploy_shm.md index b26d451bfb..ef6b7090f5 100644 --- a/docs/source/deployment/deploy_shm.md +++ b/docs/source/deployment/deploy_shm.md @@ -54,7 +54,7 @@ Before deploying the Safe Haven Management (SHM) infrastructure you need to deci Use the short name without spaces, _e.g._ **uksouth** not **UK South** ::: -Once you've decided on these, run the following command: [approx 5 minutes]: +Once you've decided on these, run the {typer}`dsh-shm-deploy` command: [approx 5 minutes]: :::{code} shell $ dsh shm deploy --entra-tenant-id YOUR_ENTRA_TENANT_ID \ diff --git a/docs/source/deployment/deploy_sre.md b/docs/source/deployment/deploy_sre.md index 5a5a5b4166..ebf1aa425a 100644 --- a/docs/source/deployment/deploy_sre.md +++ b/docs/source/deployment/deploy_sre.md @@ -21,6 +21,7 @@ $ az provider register --name Microsoft.Network Each project will have its own dedicated SRE. - Create a configuration file (optionally starting from one of our standard {ref}`policy_classification_sensitivity_tiers`) +- The {typer}`dsh-config-template` command provides template configuration files ::::{admonition} EITHER start from a blank template :class: dropdown note @@ -254,7 +255,7 @@ If you want to make changes to the config, edit this file and then run `dsh conf ## Deployment -- Deploy each SRE individually [approx 30 minutes]: +- Deploy each SRE individually using {typer}`dsh sre deploy` [approx 30 minutes]: :::{code} shell $ dsh sre deploy YOUR_SRE_NAME diff --git a/docs/source/index.md b/docs/source/index.md index 764b06ec38..2c3be84b84 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -9,6 +9,7 @@ design/index.md deployment/index.md management/index.md roles/index.md +reference/index.md contributing/index.md ::: @@ -42,6 +43,8 @@ You can read them through in order or simply jump to the section that you are mo - If you want to deploy your own Data Safe Haven. - [**Management**](management/index.md) - If you want to manage a Data Safe Haven that you (or someone else) has deployed. +- [**CLI Reference**](reference/index.md) + - If you want details of all the Command Line Interface commands. - [**Roles**](roles/index.md) - Information about the different user roles in the Data Safe Haven. - Instructions and advice for the actions of different user roles. diff --git a/docs/source/management/sre.md b/docs/source/management/sre.md index aab94c31a1..fddaa5e135 100644 --- a/docs/source/management/sre.md +++ b/docs/source/management/sre.md @@ -2,13 +2,13 @@ ## List available SRE configurations and deployment status -- Run the following if you want to check what SRE configurations are available in the current context, and whether those SREs are deployed +- Use {typer}`dsh config available` to check what SRE configurations are available in the current context, and whether those SREs are deployed. ```{code} shell $ dsh config available ``` -which will give output like the following +will give output like the following ```{code} shell Available SRE configurations for context 'green': @@ -23,7 +23,7 @@ Available SRE configurations for context 'green': ## Remove a deployed Data Safe Haven -- Run the following if you want to teardown a deployed SRE: +- Use {typer}`dsh sre teardown` to teardown a deployed SRE: ```{code} shell $ dsh sre teardown YOUR_SRE_NAME @@ -37,7 +37,7 @@ Ensure that any desired outputs have been extracted before deleting the SRE. The user groups for the SRE on Microsoft Entra ID will also be deleted. :::: -- Run the following if you want to teardown the deployed SHM: +- Use {typer}`dsh shm teardown` if you want to teardown the deployed SHM: ```{code} shell $ dsh shm teardown @@ -54,7 +54,7 @@ All SREs associated with the SHM should be torn down before the SHM is torn down SREs are modified by updating the configuration then running the deploy command. -- The existing configuration for the SRE can be shown using the following: +- The existing configuration for the SRE can be shown using {typer}`dsh config show`: ```{code} shell $ dsh config show YOUR_SRE_NAME @@ -66,14 +66,14 @@ $ dsh config show YOUR_SRE_NAME $ dsh config show YOUR_SRE_NAME --file YOUR_SRE_NAME.yaml ``` -- Edit the configuration file locally, and upload the new version: +- Edit the configuration file locally, and upload the new version using {typer}`dsh config upload`: ```{code} shell $ dsh config upload YOUR_SRE_NAME.yaml ``` - You will be shown the differences between the existing configuration and the new configuration and asked to confirm that they are correct. -- Finally, deploy your SRE to apply any changes: +- Finally, deploy your SRE using {typer}`dsh sre deploy` to apply any changes: ```{code} shell $ dsh sre deploy YOUR_SRE_NAME diff --git a/docs/source/management/user.md b/docs/source/management/user.md index d996321162..337af2302f 100644 --- a/docs/source/management/user.md +++ b/docs/source/management/user.md @@ -7,7 +7,7 @@ You will need a full name, phone number, email address and country for each user ::: 1. You can add users directly in your Entra tenant, following the instructions [here](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-create-delete-users). -1. Alternatively, you can add multiple users from a CSV file with columns named (`GivenName`, `Surname`, `Phone`, `Email`, `CountryCode`). +1. Alternatively, you can use {typer}`dsh users add` to add multiple users from a CSV file with columns named (`GivenName`, `Surname`, `Phone`, `Email`, `CountryCode`). - (Optional) you can provide a `Domain` column if you like but this will otherwise default to the domain of your SHM - {{warning}} **Phone** must be in [E.123 international format](https://en.wikipedia.org/wiki/E.123) - {{warning}} **CountryCode** is the two letter [ISO 3166-1 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) code for the country where the user is based @@ -32,7 +32,7 @@ $ dsh users add PATH_TO_MY_CSV_FILE 1. Browse to **{menuselection}`Groups --> All Groups`** 1. Click on the group named **Data Safe Haven SRE _YOUR\_SRE\_NAME_ Users** 1. Browse to **{menuselection}`Manage --> Members`** from the secondary menu on the left side -- You can do this at the command line by running the following command: +- You can do this at the command line by running `dsh users list`: ```{code} shell $ dsh users list YOUR_SRE_NAME @@ -54,7 +54,7 @@ $ dsh users add PATH_TO_MY_CSV_FILE ## Assign existing users to an SRE 1. You can do this directly in your Entra tenant by adding them to the **Data Safe Haven SRE _YOUR\_SRE\_NAME_ Users** group, following the instructions [here](https://learn.microsoft.com/en-us/entra/fundamentals/groups-view-azure-portal#add-a-group-member). -1. Alternatively, you can add multiple users from the command line: +1. Alternatively, you can add multiple users from the command line using {typer}`dsh users register`: ```{code} shell $ dsh users register YOUR_SRE_NAME -u USERNAME_1 -u USERNAME_2 @@ -69,7 +69,7 @@ $ dsh users add PATH_TO_MY_CSV_FILE ## Manually register users for self-service password reset :::{tip} -Users created via the `dsh users` command line tool will be automatically registered for SSPR. +Users created via the {typer}`dsh users` command line tool will be automatically registered for SSPR. ::: If you have manually created a user and want to enable SSPR, do the following diff --git a/docs/source/reference/config.md b/docs/source/reference/config.md new file mode 100644 index 0000000000..daffc4e2e8 --- /dev/null +++ b/docs/source/reference/config.md @@ -0,0 +1,10 @@ +# `config` + +`dsh config` commands are used to manage the configuration files that define SHMs and SREs. + +:::{typer} data_safe_haven.commands.config:config_command_group +:width: 65 +:prog: dsh config +:show-nested: +:make-sections: +::: diff --git a/docs/source/reference/context.md b/docs/source/reference/context.md new file mode 100644 index 0000000000..76b72a4ca0 --- /dev/null +++ b/docs/source/reference/context.md @@ -0,0 +1,10 @@ +# `context` + +`dsh context` commands are used to manage the Data Safe Haven contexts, which are the grouping within which a single SHM and its associated SREs are organised. + +:::{typer} data_safe_haven.commands.context:context_command_group +:width: 65 +:prog: dsh context +:show-nested: +:make-sections: +::: diff --git a/docs/source/reference/index.md b/docs/source/reference/index.md new file mode 100644 index 0000000000..6bcb99fd2e --- /dev/null +++ b/docs/source/reference/index.md @@ -0,0 +1,44 @@ +# CLI Reference + +:::{toctree} +:hidden: + +config.md +context.md +users.md +pulumi.md +shm.md +sre.md +::: + +A Data Safe Haven is managed using the `dsh` command line interface. +A full guide to the commands available for managing your Data Safe Haven is provided here. + +The `dsh` commands are the entrypoint to the Data Safe Haven command line interface. +All commands begin with `dsh`. + +:::{typer} data_safe_haven.commands.cli:application +:prog: dsh +:width: 65 +::: + +The subcommands can be used to manage various aspects of a Data Safe Haven deployment. +For further detail on each subcommand, navigate to the relevant page. + +[Config](config.md) +: Management of the configuration files used to define SHMs and SREs + +[Context](context.md) +: Manage DSH contexts, the groupings that encompass an SHM and its associated SREs + +[Users](users.md) +: Management of users in Entra ID + +[Pulumi](pulumi.md) +: An interface to the Pulumi command line interface + +[shm](shm.md) +: Management of infrastructure for DSH Safe Haven Management environments + +[sre](sre.md) +: Management of infrastructure for DSH Secure Research Environments diff --git a/docs/source/reference/pulumi.md b/docs/source/reference/pulumi.md new file mode 100644 index 0000000000..e6cb051860 --- /dev/null +++ b/docs/source/reference/pulumi.md @@ -0,0 +1,10 @@ +# `pulumi` + +The `pulumi` function allows you to run native Pulumi command line functions to interact with an SRE stack + +:::{typer} data_safe_haven.commands.pulumi:pulumi_command_group +:width: 65 +:prog: dsh pulumi +:show-nested: +:make-sections: +::: diff --git a/docs/source/reference/shm.md b/docs/source/reference/shm.md new file mode 100644 index 0000000000..0bb9f09105 --- /dev/null +++ b/docs/source/reference/shm.md @@ -0,0 +1,10 @@ +# `shm` + +`dsh shm` commands are used to deploy or teardown DSH Safe Haven Management infrastructure + +:::{typer} data_safe_haven.commands.shm:shm_command_group +:width: 65 +:prog: dsh shm +:show-nested: +:make-sections: +::: diff --git a/docs/source/reference/sre.md b/docs/source/reference/sre.md new file mode 100644 index 0000000000..03e478efe3 --- /dev/null +++ b/docs/source/reference/sre.md @@ -0,0 +1,10 @@ +# `sre` + +`dsh sre` commands are used to deploy or teardown the infrastructure for DSH Secure Research Environments + +:::{typer} data_safe_haven.commands.sre:sre_command_group +:width: 65 +:prog: dsh sre +:show-nested: +:make-sections: +::: diff --git a/docs/source/reference/users.md b/docs/source/reference/users.md new file mode 100644 index 0000000000..9b198ce5ba --- /dev/null +++ b/docs/source/reference/users.md @@ -0,0 +1,10 @@ +# `users` + +`dsh users` commands are used to manage users on the Entra ID associated with a DSH deployment. + +:::{typer} data_safe_haven.commands.users:users_command_group +:width: 65 +:prog: dsh users +:show-nested: +:make-sections: +::: diff --git a/pyproject.toml b/pyproject.toml index dc9f8d41dc..8042b11eb8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -71,6 +71,7 @@ docs = [ "pydata-sphinx-theme==0.16.0", "sphinx-togglebutton==0.3.2", "sphinx==8.1.3", + "sphinxcontrib-typer==0.5.1", ] lint = [ "ansible-dev-tools==24.11.0", @@ -120,7 +121,6 @@ lock-filename = ".hatch/requirements.txt" [tool.hatch.envs.docs] type = "pip-compile" lock-filename = ".hatch/requirements-docs.txt" -detached = true features = ["docs"] [tool.hatch.envs.docs.scripts]