Skip to content

Commit c60b0b2

Browse files
gwangmugwangmu
committed
Reference
1 parent b48b107 commit c60b0b2

File tree

1 file changed

+100
-148
lines changed

1 file changed

+100
-148
lines changed

‎docs/tools/container-engine.md‎

Lines changed: 100 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -698,191 +698,143 @@ The container image to use. Can reference a remote Docker/OCI registry or a loca
698698
```
699699
</details>
700700
701-
workdir
701+
### workdir (STRING)
702702
703-
Type: STRING
703+
Initial working directory when the container starts. Default: inherited from image.
704704
705-
Default:
706-
707-
Inherited from image
708-
709-
710-
711-
Initial working directory when the container starts.
712-
713-
714-
715-
716-
Examples
717-
718-
1. Workdir pointing to a user defined project path 
719-
720-
workdir = "/home/user/projects"
721-
722-
2. Workdir pointing to the /tmp directory
723-
724-
workdir = "/tmp"
725-
726-
727-
entrypoint
728-
729-
Type: BOOL
730-
731-
Default: true
705+
<details>
706+
<summary>Example</summary>
732707
733-
708+
* Workdir pointing to a user defined project path 
709+
```bash
710+
workdir = "/home/user/projects"
711+
```
734712
735-
If true, run the entrypoint from the container image
713+
* Workdir pointing to the /tmp directory
714+
```bash
715+
workdir = "/tmp"
716+
```
717+
</details>
736718
737719
720+
### entrypoint (BOOL)
738721
722+
If true, run the entrypoint from the container image. Default: true.
739723
740-
Examples
724+
<details>
725+
<summary>Example</summary>
741726
727+
```bash
742728
entrypoint = false
729+
```
730+
</details>
743731
744732
733+
### writable (BOOL)
745734
735+
If false, the container filesystem is read-only. Default: false.
746736
747-
writable
748-
749-
Type: BOOL
750-
751-
Default: false
752-
753-
754-
755-
If false, the container filesystem is read-only
756-
757-
758-
759-
760-
Examples
737+
<details>
738+
<summary>Example</summary>
761739
740+
```bash
762741
writable = true
742+
```
743+
</details>
763744
764745
765-
766-
767-
mounts
768-
769-
Type: ARRAY
770-
771-
Default: N/A
772-
773-
746+
### mounts (ARRAY)
774747
775748
List of bind mounts in the format SOURCE:DESTINATION[:FLAGS]. Flags are optional and can include ro, private, etc.
776749
777-
Mount flags are separated with a plus symbol, for example: ro+private.
778-
Optional flags from docker format or OCI (need reference)
779-
780-
781-
782-
783-
784-
785-
786-
Examples
787-
788-
Literal fixed mount map
789-
mounts = ["/capstor/scratch/cscs/amadonna:/capstor/scratch/cscs/amadonna"]
790-
791-
2. Mapping path with env variable expansion
792-
793-
mounts = ["/capstor/scratch/cscs/${USER}:/capstor/scratch/cscs/${USER}"]
794-
795-
3. Mounting the scratch filesystem using a host environment variable
796-
797-
mounts = ["${SCRATCH}:/scratch"]
798-
799-
800-
801-
802-
env
803-
804-
Type: TABLE
805-
806-
Default:
807-
808-
Inherited from
809-
810-
host and
811-
812-
image
813-
814-
815-
816-
Environment variables to set in the container. Null-string values will unset the variable.
817-
818-
By default, containers inherit environment variables from the container image and the host environment, with variables from the image taking precedence.
819-
The env table can be used to further customize the container environment by setting, modifying, or unsetting variables.
820-
Values of the table entries must be strings. If an entry has a null value, the variable corresponding to the entry key is unset in the container.
821-
822-
823-
824-
Examples
825-
826-
1. Basic env block
827-
828-
[env]
829-
MY_RUN = "production",
830-
DEBUG = "false"
831-
2. Use of environment variable expansion
832-
[env]
833-
MY_NODE = "${VAR_FROM_HOST}",
834-
PATH = "${PATH}:/custom/bin",
835-
DEBUG = "true"
836-
837-
838-
839-
840-
841-
842-
843-
844-
annotations
845-
846-
Type: TABLE
750+
<details>
751+
<summary>Notes</summary>
847752
848-
Default: N/A
753+
* Mount flags are separated with a plus symbol, for example: ro+private.
754+
* Optional flags from docker format or OCI (need reference)
755+
</details>
849756
850-
757+
<details>
758+
<summary>Example</summary>
851759
852-
OCI-like annotations for the container.
760+
* Literal fixed mount map
761+
```bash
762+
mounts = ["/capstor/scratch/cscs/amadonna:/capstor/scratch/cscs/amadonna"]
763+
```
853764
854-
For more details, refer to the Annotations section.
765+
* Mapping path with env variable expansion
766+
```bash
767+
mounts = ["/capstor/scratch/cscs/${USER}:/capstor/scratch/cscs/${USER}"]
768+
```
855769
856-
 
770+
* Mounting the scratch filesystem using a host environment variable
771+
```bash
772+
mounts = ["${SCRATCH}:/scratch"]
773+
```
774+
</details>
857775
858776
777+
### env (TABLE)
859778
779+
Environment variables to set in the container. Null-string values will unset the variable. Default: inherited from the host and the image.
860780
861-
Examples
781+
<details>
782+
<summary>Notes</summary>
862783
863-
1. Disabling the CXI hook
784+
* By default, containers inherit environment variables from the container image and the host environment, with variables from the image taking precedence.
785+
* The env table can be used to further customize the container environment by setting, modifying, or unsetting variables.
786+
* Values of the table entries must be strings. If an entry has a null value, the variable corresponding to the entry key is unset in the container.
787+
</details>
864788
865-
[annotations]
866-
com.hooks.cxi.enabled = "false"
789+
<details>
790+
<summary>Example</summary>
867791
868-
2. Control of SSH hook parameters via annotation and variable expansion
792+
* Basic env block
793+
```bash
794+
[env]
795+
MY_RUN = "production",
796+
DEBUG = "false"
797+
```
869798
870-
[annotations.com.hooks.ssh]
871-
authorize_ssh_key = "/capstor/scratch/cscs/${USER}/tests/edf/authorized_keys"
872-
enabled = "true"
799+
* Use of environment variable expansion
800+
```bash
801+
[env]
802+
MY_NODE = "${VAR_FROM_HOST}",
803+
PATH = "${PATH}:/custom/bin",
804+
DEBUG = "true"
805+
```
806+
</details>
873807
874-
3. Alternative example for usage of annotation with fixed path
875808
876-
[annotations]
877-
com.hooks.ssh.authorize_ssh_key = "/path/to/authorized_keys"
878-
com.hooks.ssh.enabled = "true"
809+
### annotations (TABLE)
879810
811+
OCI-like annotations for the container. For more details, refer to the Annotations section.
880812
813+
<details>
814+
<summary>Example</summary>
881815
816+
* Disabling the CXI hook
817+
```bash
818+
[annotations]
819+
com.hooks.cxi.enabled = "false"
820+
```
882821
822+
* Control of SSH hook parameters via annotation and variable expansion
823+
```bash
824+
[annotations.com.hooks.ssh]
825+
authorize_ssh_key = "/capstor/scratch/cscs/${USER}/tests/edf/authorized_keys"
826+
enabled = "true"
827+
```
883828
829+
* Alternative example for usage of annotation with fixed path
830+
```bash
831+
[annotations]
832+
com.hooks.ssh.authorize_ssh_key = "/path/to/authorized_keys"
833+
com.hooks.ssh.enabled = "true"
834+
```
835+
</details>
884836
885-
Environment variable expansion and relative paths expansion are only available on the Bristen vCluster as technical preview.
837+
> **INFO**: Environment variable expansion and relative paths expansion are only available on the Bristen vCluster as technical preview.
886838
887839
### Environment Variable Expansion
888840
@@ -895,9 +847,9 @@ Environment variable expansion allows for dynamic substitution of environment va
895847
* *Limitations*
896848
* Variables defined within the [env] EDF table cannot reference other entries from [env] tables in the same or other EDF files (e.g. the ones entered as base environments) . Therefore, only environment variables from the host or image can be referenced.
897849
* *Environment Variable Resolution Order*. The environment variables are resolved based on the following order:
898-
1. TOML env: Variable values as defined in EDF’s env.
899-
2. Container Image: Variables defined in the container image's environment take precedence.
900-
3. Host Environment: Environment variables defined in the host system.
850+
* TOML env: Variable values as defined in EDF’s env.
851+
* Container Image: Variables defined in the container image's environment take precedence.
852+
* Host Environment: Environment variables defined in the host system.
901853
902854
### Relative paths expansion
903855
@@ -911,7 +863,7 @@ Alpine Linux is incompatible with some hooks, causing errors when used with Slur
911863
912864
```bash
913865
[<vcluster>][<username>@<vcluster>-ln001 ~]$ cat alpine.toml
914-
image = "alpine:3.19"
866+
image = "alpine: *19"
915867
[<vcluster>][<username>@<vcluster>-ln001 ~]$ srun -lN1 --environment=alpine.toml echo "abc"
916868
0: slurmstepd: error: pyxis: container start failed with error code: 1
917869
0: slurmstepd: error: pyxis: printing enroot log file:
@@ -926,7 +878,7 @@ This is because some hooks (e.g., Slurm and CXI hooks) leverage `ldconfig` (from
926878
927879
```bash
928880
[<vcluster>][<username>@<vcluster>-ln001 ~]$ cat alpine_workaround.toml
929-
image = "alpine:3.19"
881+
image = "alpine: *19"
930882
[annotations]
931883
com.hooks.slurm.enabled = "false"
932884
com.hooks.cxi.enabled = "false"

0 commit comments

Comments
 (0)