From ff3d758a7f328d4c6e1f139c5de17149dbdf7455 Mon Sep 17 00:00:00 2001 From: Declan Valters Date: Thu, 8 Aug 2024 12:46:19 +0100 Subject: [PATCH 1/4] Set up skeleton layout of the TRE docs section --- .../advise-ig-required-software-stack.md | 0 .../building-and-testing-containers.md | 0 .../tre-container-user-guide/development-workflow.md | 0 .../tre-container-user-guide/introduction.md | 0 .../tre-container-user-guide/using-containers-in-the-tre.md | 0 mkdocs.yml | 6 ++++++ 6 files changed, 6 insertions(+) create mode 100644 docs/safe-haven-services/tre-container-user-guide/advise-ig-required-software-stack.md create mode 100644 docs/safe-haven-services/tre-container-user-guide/building-and-testing-containers.md create mode 100644 docs/safe-haven-services/tre-container-user-guide/development-workflow.md create mode 100644 docs/safe-haven-services/tre-container-user-guide/introduction.md create mode 100644 docs/safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md diff --git a/docs/safe-haven-services/tre-container-user-guide/advise-ig-required-software-stack.md b/docs/safe-haven-services/tre-container-user-guide/advise-ig-required-software-stack.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/safe-haven-services/tre-container-user-guide/building-and-testing-containers.md b/docs/safe-haven-services/tre-container-user-guide/building-and-testing-containers.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/safe-haven-services/tre-container-user-guide/development-workflow.md b/docs/safe-haven-services/tre-container-user-guide/development-workflow.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/safe-haven-services/tre-container-user-guide/introduction.md b/docs/safe-haven-services/tre-container-user-guide/introduction.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md b/docs/safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md new file mode 100644 index 000000000..e69de29bb diff --git a/mkdocs.yml b/mkdocs.yml index 05b7140b4..4cba9243f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -97,6 +97,12 @@ nav: - "Submitting Scripts to Slurm": safe-haven-services/superdome-flex-tutorial/L3_submitting_scripts_to_slurm.md - "Parallelised Python Analysis": safe-haven-services/superdome-flex-tutorial/L4_parallelised_python_analysis.md - "Parallelised R Analysis": safe-haven-services/superdome-flex-tutorial/L5_parallelised_r_analysis.md + - "TRE Container User Guide": + - "Introduction": safe-haven-services/tre-container-user-guide/introduction.md + - "Development Workflow": safe-haven-services/tre-container-user-guide/development-workflow.md + - "Advising IG of required software stack": safe-haven-services/tre-container-user-guide/advise-ig-required-software-stack.md + - "Building and Testing Containers": safe-haven-services/tre-container-user-guide/building-and-testing-containers.md + - "Using Containers in the TRE": safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md - "EIDF Known Issues": known-issues/index.md - "EIDF Frequently Asked Questions": faq/index.md From 85ac7e01d116f78350e0b74bc823b2956f4d0041 Mon Sep 17 00:00:00 2001 From: Declan Valters Date: Thu, 8 Aug 2024 14:41:20 +0100 Subject: [PATCH 2/4] Tweaks to TRE guide formatting --- .../advise-ig-required-software-stack.md | 3 + .../development-workflow.md | 25 ++++++++ .../tre-container-user-guide/introduction.md | 7 +++ .../using-containers-in-the-tre.md | 58 +++++++++++++++++++ 4 files changed, 93 insertions(+) diff --git a/docs/safe-haven-services/tre-container-user-guide/advise-ig-required-software-stack.md b/docs/safe-haven-services/tre-container-user-guide/advise-ig-required-software-stack.md index e69de29bb..c5297afed 100644 --- a/docs/safe-haven-services/tre-container-user-guide/advise-ig-required-software-stack.md +++ b/docs/safe-haven-services/tre-container-user-guide/advise-ig-required-software-stack.md @@ -0,0 +1,3 @@ +# Advising Information Governance of required software stack + +Projects must establish that the software stack they intend to import in the container is acceptable for the project’s IG approvals. Projects should only seek to use container-based software if the standard TRE desktop environment is not sufficient for the research scope. However, it is broadly understood that the standard desktop software, whilst useful in most cases, is inadequate for many purposes and specifically ML, and software import using containers is intended to address this. diff --git a/docs/safe-haven-services/tre-container-user-guide/development-workflow.md b/docs/safe-haven-services/tre-container-user-guide/development-workflow.md index e69de29bb..c181ce519 100644 --- a/docs/safe-haven-services/tre-container-user-guide/development-workflow.md +++ b/docs/safe-haven-services/tre-container-user-guide/development-workflow.md @@ -0,0 +1,25 @@ +# Development workflow + +The general guidance for TRE container development is: + +- Develop all code on a git platform, typically GitHub or a university managed GitLab service + +- Start Dockerfiles from a well-known base image. This is especially important if using a GPU as your container will need to have a compatible version of CUDA (currently 11.1 or later) + +- Add all the additional content (code files, libraries, packages, data, and licences) needed for your analysis work to your Dockerfile + +- Build and test the container to ensure that it has no external runtime dependencies + +- Push the Dockerfile to the project git repository so the container image build is recorded + +- Push the container image to the GitHub container registry ghcr.io (GHCR) + +- Login to a TRE desktop enabled for container execution to pull and run the container + +Containers are connected to three external directories when run inside the TRE: one for access to the project data files (which may be read-only in some cases); one for temporary work files that are all deleted when the container exits; and one for the job output files (which may be set as read-only in some cases when the container exits). All container outputs remain inside the TRE project file space and there is no automatic export when the container finishes. + +Container images that have been pulled into the TRE are destroyed after they have been run. Only the files written to the container outputs directory are guaranteed to be retained. + +You must ensure that, apart from the input data, your container has everything that it needs to run, including all code and dependencies, and any ancillary files such as machine learning models. It is likely that your development environment, which is always outside the TRE, does not normally have these three directories, but you need to build a container that uses them (see below for path names) because there is no ability inside the TRE to change which directories are available. + +The input data file names may change so you may not want to hard-code them into your container. For example, instead of your code using `open("/safe_data/my_patients.csv")` you should consider putting a list of input file names into a config file and reading that config file in your container start up to determine which input data files to use. This will allow you to re-run your container on different data sets much faster than building a new container each time. diff --git a/docs/safe-haven-services/tre-container-user-guide/introduction.md b/docs/safe-haven-services/tre-container-user-guide/introduction.md index e69de29bb..a6305b3a6 100644 --- a/docs/safe-haven-services/tre-container-user-guide/introduction.md +++ b/docs/safe-haven-services/tre-container-user-guide/introduction.md @@ -0,0 +1,7 @@ +# Introduction + +This guide sets out the required activities for researchers using containers in the EPCC TRE (Safe Haven). The intended audience are software developers with experience of containers and Docker and Podman in particular. Online courses such as [Intro to Containers](https://github.com/ImperialCollegeLondon/RCDS-intro-to-containers) demonstrate the base skills needed if there is any doubt. + +The Container Execution Service (CES) has been introduced to allow project code developed and tested by researchers outside the TRE in personal development environments to be imported and run on the project data inside the TRE using a well-documented, transparent, secure workflow. The primary role of the TRE is to store and share data securely; it is not intended to be a software development and testing environment. The CES removes the need for software development in the TRE. + +The use of containers and software configuration management processes is also strongly advocated by the research software engineering community for experiment management and reproducibility. It is recommended that TRE container builders take a disciplined approach to code management and use git to create container build audit trails to satisfy any IG (Information Governance) concerns about the provenance of the project code. diff --git a/docs/safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md b/docs/safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md index e69de29bb..92efac5f0 100644 --- a/docs/safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md +++ b/docs/safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md @@ -0,0 +1,58 @@ +# Using containers in the TRE + +Once you have built and tested your container, you are ready to start using it within the TRE. + +## Pulling container into the TRE + +Containers can only be used on the TRE desktop hosts using shell commands. And containers can only be pulled from the GitHub Container Registry (GHCR) into the TRE using a `ces-pull` script. Hence containers must be pushed to GHCR for them to be used in the TRE. + +As use of containers in the TRE is a new service, it is at this stage regarded as an activity that requires additional security controls. As result the `ces-pull` command is a privileged one that can only be run using sudo. Researcher accounts must be explicitly enabled for use of the sudo `ces-pull` command through IG approval – sudo access for these accounts will be constrained to only run the `ces-pull` command. + +To pull a private image, you must create an access token to authenticate with GHCR (see [Authenticating to the container registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry)). The container is then pulled by the user with the command: + +```bash +sudo ces-pull ghcr.io//[:] +``` + +To pull a public image, which does not require authenticating with username and token, pass two empty strings: + +```bash +sudo ces-pull "" "" ghcr.io//[:] +``` + +Once the container image has been pulled into the TRE desktop host, the image can be managed with Podman commands. However, containers must not be run directly using Podman. Instead, commands developed for use within the TRE must be used as will now be described. + +## Running the container in the TRE + +Containers may be run in the TRE using one of two commands: use `ces-gpu-run` if a GPU is to be connected to the container, otherwise use the `ces-run` command. The sudo privilege escalation is not required to run containers. The basic command to start a container is one of: + +```bash +ces-run ghcr.io//[:] +``` + +or, if your container requires a GPU: + +```bash +ces-gpu-run ghcr.io//[:] +``` + +Each command supports a number of options to control resource allocation and to pass parameters to the podman run command and to the container itself. Each command has a help option to output the following information: + +```bash +Usage: +ces-run [options] +Available Options: +-c|--cores CPU cores to allocate (default is sharing all of them) +--dry-run Do not run the container, print out all the command options +--env-file File with env vars to pass to container +-h|--help Print this stuff +-m|--memory Memory to allocate in Gb (default is 4Gb) +-n|--name Assign a name to the container +--opt-file File with additional options to pass to run command +-v|--verbose Print out all command options +--version Print out version string +``` + +The `--env-file` and `--opt-file` arguments can be used to extend the command-line script that is executed when the container is started. The `--env-file` option is exactly the docker and podman run option with the file containing lines of the form `Variable=Value`. See the [Docker option reference](https://docs.docker.com/reference/cli/docker/container/run/#env) + +The `--opt-file` option allows you to have a file containing additional arguments to the `ces-run` and `ces-gpu-run` command. From 455c07ae0dd04ff4c75d62bbba03cfc3c7443014 Mon Sep 17 00:00:00 2001 From: gdeiana Date: Thu, 8 Aug 2024 15:27:48 +0100 Subject: [PATCH 3/4] Added content to building-and-testing-containers.md --- .gitignore | 1 + .../building-and-testing-containers.md | 60 +++++++++++++++++++ 2 files changed, 61 insertions(+) diff --git a/.gitignore b/.gitignore index 62e703bb4..138da494a 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ _build/ site/ .idea/ .envloc +mkdocs-material/ \ No newline at end of file diff --git a/docs/safe-haven-services/tre-container-user-guide/building-and-testing-containers.md b/docs/safe-haven-services/tre-container-user-guide/building-and-testing-containers.md index e69de29bb..a57df296a 100644 --- a/docs/safe-haven-services/tre-container-user-guide/building-and-testing-containers.md +++ b/docs/safe-haven-services/tre-container-user-guide/building-and-testing-containers.md @@ -0,0 +1,60 @@ +# Building and Testing Containers + +## Choose a container base from DockerHub +Projects should build containers by starting with a well-known application base container on a public registry. Projects should add a minimum of additional project software and packages so that the container is clearly built for a specific purpose. Containers built for one specific batch job, either a data transformation or analysis, are examples of this approach. Container builds that assemble groups of tools and then used to run a variety of tasks should be avoided. Additionally, container builds that start from generic distributions such as Debian or Ubuntu should also be avoided as leaner and more focussed application and language containers are already available. + +Examples of batch job container bases are Python and PyTorch, and other language specific and ML software stacks. Examples of interactive container bases are Rocker, Jupyter Docker Stacks, and NVIDIA RAPIDS extended with additional package sets and code required by your project. + +## Add TRE file system directories +Container images built to run in the TRE must implement the following line in the Dockerfile to interface with the project data and the TRE file system: + +```docker +RUN mkdir /safe_data /safe_outputs /scratch +``` + +The project’s private `/safe_data/` directory is mapped to the container’s `/safe_data` directory. A unique container job output directory is created in the user's home directory and mapped to `/safe_outputs` in the container. And `/scratch` is a temporary workspace that is deleted when the container exits. If the container processing uses the `TMP` environment variable, it should be set to the `/scratch` volume mount. +Hence, containers have access to three directories located on the host system as detailed in the following table: + +| Directory on host system | Directory in container | Intended use +| -------- | ------- | ------- | +| /safe_data//|/safe_data|Read-only access if required by IG, or read-write access, to data and other project files.| +|~/outputs_ |/safe_outputs |Will be created at container startup as an empty directory. Intended for any outputs: logs, data, models.| +|~/scratch_|/scratch|Temporary directory that is removed after container termination on the host system. Any temporary files should be placed here.| + +Currently, temporary files can also be written into any directory in the container’s internal file system. This is allowed to prevent container software failure when it is dependent on the container file system being writable. However, the use of `/scratch` is encouraged for two reasons: + +1. In the future, write access to the container file system might be prevented for security reasons. Further, the space available on the container’s internal file system is limited compared to the space available on `/scratch`. Writing only to `/scratch` at runtime is therefore future proof. +2. Use of `/scratch` can be more efficient if the service is able to mount it on high-performing storage devices. + +## Install and copy project code into container +Research software stacks are complex and dependent on many package sets and libraries, and sometimes on specific version combinations of these. The container build process presents the project team with the opportunity to manage and resolve these dependencies before contact with the project data in the restricted TRE setting. + +Unlike the TRE desktop servers, containers do not have access to external network repositories, and do not have access to external licence servers. Any container software that requires a licence to run must be copied into the container at build time. EPCC are not responsible for verifying that the appropriate licences are installed or that license terms are being met. + +Projects using configuration files for multiple containers, for example ML models, can also import these to the TRE directly by copying them to the project `/safe_data` file system. + +Batch jobs built to run as containers should start directly from the `ENTRYPOINT` or `CMD` section of the Dockerfile. Batch jobs should run without any user interaction after start, should read input from the `/safe_data` directory and write outputs to the `/scratch` and `/safe_outputs` directories. + +Interactive containers should present a connection port for the user session. Once the container is started the user can connect to the session port from the TRE desktop. If code files are being changed during the session these should be saved on the `/safe_data` or the `/safe_outputs` directories as the internal container file space is not preserved when the session ends. + +## Test the container for TRE use +When the container is running in the TRE it will not have any external network or internet access. If the code, or any of its dependencies, rely on data files downloaded at runtime (for example machine learning models) this will fail in the TRE. Code must be modified to load these files explicitly from a file path which is accessible from inside the container. + +An example of TRE network isolation significance and the considerations arising from this is provided by Hugging Face, where models are cached in the user local `~/.cache/huggingface/hub/` directory in the container. The environment variable `HF_HOME` must be set to a directory in a `/safe_data` project folder and the `cache_dir` option of the `from_pretrained()` call used at runtime. + +If a model is downloaded from Hugging Face the advice is to set the environment variable `HF_HUB_OFFLINE=1` to prevent attempts at contact the Hugging Face Hub. Any connection attempts will take a significant time to elapse and then fail in the TRE setting. + +It is recommended that the checklist for Dockerfile composition is followed: https://github.com/EPCCed/tre-container-samples/blob/main/docs/container-build-guide.md + +Information Governance requirements may require a security scan of your container, and [Trivy](https://trivy.dev/) is a tool that can help with this task. Trivy inspects container images to find items which have known vulnerabilities and produces a report that may be used to help assess the risk. The use of the Trivy misconfiguration tool on Dockerfiles is also recommended. This tool option will highlight many common security issues: + +```bash +docker run --rm -v $(pwd):/repo ghcr.io/aquasecurity/trivy:latest config "/repo/Dockerfile" +``` + +The security posture of containers and the build process may be of interest to IG teams, however, it is not expected that security issues indicated by the tool need to be addressed before the container is run in the TRE unless the IG team issues specific guidance on vulnerability and configuration remediation and mitigation. + +## Scan container using Trivy CI +Trivy can be run manually but it is easier to have it run automatically whenever you update your container image. An example GitHub Actions workflow to run Trivy and publish the outputs can be found here: https://github.com/EPCCed/tre-container-samples/blob/main/.github/workflows/main.yaml + +The Trivy report can be downloaded as an artifact from the job summary page. Before using a specific container in the TRE it may be necessary to test the security risk and gain IG team approval. From 6428e5b421f41d06545fad4cc274b5a10bdbea26 Mon Sep 17 00:00:00 2001 From: Declan Valters Date: Thu, 8 Aug 2024 16:04:54 +0100 Subject: [PATCH 4/4] Tidy a couple of tiny formatting issues --- .../building-and-testing-containers.md | 27 +++++++++++-------- .../using-containers-in-the-tre.md | 4 +-- mkdocs.yml | 2 +- 3 files changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/safe-haven-services/tre-container-user-guide/building-and-testing-containers.md b/docs/safe-haven-services/tre-container-user-guide/building-and-testing-containers.md index a57df296a..28266b6c2 100644 --- a/docs/safe-haven-services/tre-container-user-guide/building-and-testing-containers.md +++ b/docs/safe-haven-services/tre-container-user-guide/building-and-testing-containers.md @@ -1,11 +1,13 @@ # Building and Testing Containers ## Choose a container base from DockerHub + Projects should build containers by starting with a well-known application base container on a public registry. Projects should add a minimum of additional project software and packages so that the container is clearly built for a specific purpose. Containers built for one specific batch job, either a data transformation or analysis, are examples of this approach. Container builds that assemble groups of tools and then used to run a variety of tasks should be avoided. Additionally, container builds that start from generic distributions such as Debian or Ubuntu should also be avoided as leaner and more focussed application and language containers are already available. -Examples of batch job container bases are Python and PyTorch, and other language specific and ML software stacks. Examples of interactive container bases are Rocker, Jupyter Docker Stacks, and NVIDIA RAPIDS extended with additional package sets and code required by your project. +Examples of batch job container bases are Python and PyTorch, and other language specific and ML software stacks. Examples of interactive container bases are Rocker, Jupyter Docker Stacks, and NVIDIA RAPIDS extended with additional package sets and code required by your project. ## Add TRE file system directories + Container images built to run in the TRE must implement the following line in the Dockerfile to interface with the project data and the TRE file system: ```docker @@ -15,36 +17,38 @@ RUN mkdir /safe_data /safe_outputs /scratch The project’s private `/safe_data/` directory is mapped to the container’s `/safe_data` directory. A unique container job output directory is created in the user's home directory and mapped to `/safe_outputs` in the container. And `/scratch` is a temporary workspace that is deleted when the container exits. If the container processing uses the `TMP` environment variable, it should be set to the `/scratch` volume mount. Hence, containers have access to three directories located on the host system as detailed in the following table: -| Directory on host system | Directory in container | Intended use +| Directory on host system | Directory in container | Intended use | -------- | ------- | ------- | -| /safe_data//|/safe_data|Read-only access if required by IG, or read-write access, to data and other project files.| -|~/outputs_ |/safe_outputs |Will be created at container startup as an empty directory. Intended for any outputs: logs, data, models.| -|~/scratch_|/scratch|Temporary directory that is removed after container termination on the host system. Any temporary files should be placed here.| +| `/safe_data//`|/`safe_data`|Read-only access if required by IG, or read-write access, to data and other project files.| +|`~/outputs_` |`/safe_outputs` |Will be created at container startup as an empty directory. Intended for any outputs: logs, data, models.| +|`~/scratch_`|`/scratch`|Temporary directory that is removed after container termination on the host system. Any temporary files should be placed here.| Currently, temporary files can also be written into any directory in the container’s internal file system. This is allowed to prevent container software failure when it is dependent on the container file system being writable. However, the use of `/scratch` is encouraged for two reasons: -1. In the future, write access to the container file system might be prevented for security reasons. Further, the space available on the container’s internal file system is limited compared to the space available on `/scratch`. Writing only to `/scratch` at runtime is therefore future proof. -2. Use of `/scratch` can be more efficient if the service is able to mount it on high-performing storage devices. + 1. In the future, write access to the container file system might be prevented for security reasons. Further, the space available on the container’s internal file system is limited compared to the space available on `/scratch`. Writing only to `/scratch` at runtime is therefore future proof. + 1. Use of `/scratch` can be more efficient if the service is able to mount it on high-performing storage devices. ## Install and copy project code into container + Research software stacks are complex and dependent on many package sets and libraries, and sometimes on specific version combinations of these. The container build process presents the project team with the opportunity to manage and resolve these dependencies before contact with the project data in the restricted TRE setting. Unlike the TRE desktop servers, containers do not have access to external network repositories, and do not have access to external licence servers. Any container software that requires a licence to run must be copied into the container at build time. EPCC are not responsible for verifying that the appropriate licences are installed or that license terms are being met. Projects using configuration files for multiple containers, for example ML models, can also import these to the TRE directly by copying them to the project `/safe_data` file system. -Batch jobs built to run as containers should start directly from the `ENTRYPOINT` or `CMD` section of the Dockerfile. Batch jobs should run without any user interaction after start, should read input from the `/safe_data` directory and write outputs to the `/scratch` and `/safe_outputs` directories. +Batch jobs built to run as containers should start directly from the `ENTRYPOINT` or `CMD` section of the Dockerfile. Batch jobs should run without any user interaction after start, should read input from the `/safe_data` directory and write outputs to the `/scratch` and `/safe_outputs` directories. -Interactive containers should present a connection port for the user session. Once the container is started the user can connect to the session port from the TRE desktop. If code files are being changed during the session these should be saved on the `/safe_data` or the `/safe_outputs` directories as the internal container file space is not preserved when the session ends. +Interactive containers should present a connection port for the user session. Once the container is started the user can connect to the session port from the TRE desktop. If code files are being changed during the session these should be saved on the `/safe_data` or the `/safe_outputs` directories as the internal container file space is not preserved when the session ends. ## Test the container for TRE use + When the container is running in the TRE it will not have any external network or internet access. If the code, or any of its dependencies, rely on data files downloaded at runtime (for example machine learning models) this will fail in the TRE. Code must be modified to load these files explicitly from a file path which is accessible from inside the container. An example of TRE network isolation significance and the considerations arising from this is provided by Hugging Face, where models are cached in the user local `~/.cache/huggingface/hub/` directory in the container. The environment variable `HF_HOME` must be set to a directory in a `/safe_data` project folder and the `cache_dir` option of the `from_pretrained()` call used at runtime. If a model is downloaded from Hugging Face the advice is to set the environment variable `HF_HUB_OFFLINE=1` to prevent attempts at contact the Hugging Face Hub. Any connection attempts will take a significant time to elapse and then fail in the TRE setting. -It is recommended that the checklist for Dockerfile composition is followed: https://github.com/EPCCed/tre-container-samples/blob/main/docs/container-build-guide.md +It is recommended that the checklist for Dockerfile composition is followed: [Container Build Guide](https://github.com/EPCCed/tre-container-samples/blob/main/docs/container-build-guide.md) Information Governance requirements may require a security scan of your container, and [Trivy](https://trivy.dev/) is a tool that can help with this task. Trivy inspects container images to find items which have known vulnerabilities and produces a report that may be used to help assess the risk. The use of the Trivy misconfiguration tool on Dockerfiles is also recommended. This tool option will highlight many common security issues: @@ -55,6 +59,7 @@ docker run --rm -v $(pwd):/repo ghcr.io/aquasecurity/trivy:latest config "/repo/ The security posture of containers and the build process may be of interest to IG teams, however, it is not expected that security issues indicated by the tool need to be addressed before the container is run in the TRE unless the IG team issues specific guidance on vulnerability and configuration remediation and mitigation. ## Scan container using Trivy CI -Trivy can be run manually but it is easier to have it run automatically whenever you update your container image. An example GitHub Actions workflow to run Trivy and publish the outputs can be found here: https://github.com/EPCCed/tre-container-samples/blob/main/.github/workflows/main.yaml + +Trivy can be run manually but it is easier to have it run automatically whenever you update your container image. An example GitHub Actions workflow to run Trivy and publish the outputs can be found [here](https://github.com/EPCCed/tre-container-samples/blob/main/.github/workflows/main.yaml) The Trivy report can be downloaded as an artifact from the job summary page. Before using a specific container in the TRE it may be necessary to test the security risk and gain IG team approval. diff --git a/docs/safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md b/docs/safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md index 92efac5f0..855e7b19f 100644 --- a/docs/safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md +++ b/docs/safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md @@ -1,8 +1,8 @@ -# Using containers in the TRE +# Using Containers in the TRE Once you have built and tested your container, you are ready to start using it within the TRE. -## Pulling container into the TRE +## Pulling a container into the TRE Containers can only be used on the TRE desktop hosts using shell commands. And containers can only be pulled from the GitHub Container Registry (GHCR) into the TRE using a `ces-pull` script. Hence containers must be pushed to GHCR for them to be used in the TRE. diff --git a/mkdocs.yml b/mkdocs.yml index 4cba9243f..3294acf9a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -100,7 +100,7 @@ nav: - "TRE Container User Guide": - "Introduction": safe-haven-services/tre-container-user-guide/introduction.md - "Development Workflow": safe-haven-services/tre-container-user-guide/development-workflow.md - - "Advising IG of required software stack": safe-haven-services/tre-container-user-guide/advise-ig-required-software-stack.md + - "Advising IG of Required Software Stack": safe-haven-services/tre-container-user-guide/advise-ig-required-software-stack.md - "Building and Testing Containers": safe-haven-services/tre-container-user-guide/building-and-testing-containers.md - "Using Containers in the TRE": safe-haven-services/tre-container-user-guide/using-containers-in-the-tre.md - "EIDF Known Issues": known-issues/index.md