Skip to content

Commit f7327b0

Browse files
vsochvsoch
committed
adding inspect docs
1 parent cbadcfb commit f7327b0

File tree

2 files changed

+242
-0
lines changed

2 files changed

+242
-0
lines changed

‎_data/sidebars/user_docs.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,10 @@ entries:
7575
url: /docs-import
7676
output: web, pdf
7777

78+
- title: inspect
79+
url: /docs-inspect
80+
output: web, pdf
81+
7882
- title: pull
7983
url: /docs-pull
8084
output: web, pdf

‎pages/docs/user-docs/docs-inspect.md

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
---
2+
title: Singularity Inspect
3+
sidebar: user_docs
4+
permalink: docs-inspect
5+
toc: false
6+
folder: docs
7+
---
8+
9+
How can you sniff an image? We have provided the inspect command for you to easily see the runscript, test script, environment, and metadata labels.
10+
11+
{% include toc.html %}
12+
13+
## Usage
14+
15+
```bash
16+
$ singularity inspect --help
17+
18+
USAGE: singularity [...] inspect [exec options...] <container path>
19+
20+
This command will show you the runscript for the image.
21+
22+
INSPECT OPTIONS:
23+
-l/--labels Show the labels associated with the image (default)
24+
-d/--deffile Show the bootstrap definition file which was used
25+
to generate this image
26+
-r/--runscript Show the runscript for this image
27+
-t/--test Show the test script for this image
28+
-e/--environment Show the environment settings for this container
29+
-j/--json Print structured json instead of sections
30+
31+
EXAMPLES:
32+
33+
$ singularity inspect ubuntu.img
34+
#!/bin/sh
35+
36+
exec /bin/bash "$@"
37+
38+
$ singuarity inspect --labels ubuntu.img
39+
{
40+
"SINGULARITY_DEFFILE_BOOTSTRAP": "docker",
41+
"SINGULARITY_DEFFILE": "Singularity",
42+
"SINGULARITY_DEFFILE_FROM": "ubuntu:latest",
43+
"SINGULARITY_BOOTSTRAP_VERSION": "2.2.99"
44+
}
45+
46+
47+
For additional help, please visit our public documentation pages which are
48+
found at:
49+
50+
http://singularity.lbl.gov/
51+
52+
```
53+
54+
This inspect is essential for making containers understandable by other tools and applications.
55+
56+
57+
## JSON Api Standard
58+
For any inspect command, by adding `--json` you can be assured to get a <a href="http://jsonapi.org/" target="_blank">JSON API</a> standardized response, for example:
59+
60+
```
61+
singularity inspect -l --json ubuntu.img
62+
{
63+
"data": {
64+
"attributes": {
65+
"labels": {
66+
"SINGULARITY_DEFFILE_BOOTSTRAP": "docker",
67+
"SINGULARITY_DEFFILE": "Singularity",
68+
"SINGULARITY_BOOTSTRAP_VERSION": "2.2.99",
69+
"SINGULARITY_DEFFILE_FROM": "ubuntu:latest"
70+
}
71+
},
72+
"type": "container"
73+
}
74+
}
75+
```
76+
77+
## Inspect Flags
78+
The default, if run without any arguments, will show you the container labels file
79+
80+
```
81+
$ singularity inspect ubuntu.img
82+
{
83+
"SINGULARITY_DEFFILE_BOOTSTRAP": "docker",
84+
"SINGULARITY_DEFFILE": "Singularity",
85+
"SINGULARITY_BOOTSTRAP_VERSION": "2.2.99",
86+
"SINGULARITY_DEFFILE_FROM": "ubuntu:latest"
87+
}
88+
89+
```
90+
91+
and as outlined in the usage, you can specify to see any combination of `--labels`, `--environment`, `--runscript`, `--test`, and `--deffile`. The quick command to see everything, in json format, would be:
92+
93+
```
94+
$ singularity inspect -l -r -d -t -e -j ubuntu.img
95+
{
96+
"data": {
97+
"attributes": {
98+
"test": null,
99+
"environment": "# Custom environment shell code should follow\n\n",
100+
"labels": {
101+
"SINGULARITY_DEFFILE_BOOTSTRAP": "docker",
102+
"SINGULARITY_DEFFILE": "Singularity",
103+
"SINGULARITY_BOOTSTRAP_VERSION": "2.2.99",
104+
"SINGULARITY_DEFFILE_FROM": "ubuntu:latest"
105+
},
106+
"deffile": "Bootstrap:docker\nFrom:ubuntu:latest\n",
107+
"runscript": "#!/bin/sh\n\nexec /bin/bash \"$@\""
108+
},
109+
"type": "container"
110+
}
111+
}
112+
```
113+
114+
### Labels
115+
The default, if run without any arguments, will show you the container labels file (located at `/.singularity.d/labels.json` in the container. These labels are the ones that you define in the `%labels` section of your bootstrap file, along with any Docker `LABEL` that came with an image that you imported, and other metadata about the bootstrap. For example, here we are inspecting labels for `ubuntu.img`
116+
117+
```
118+
$ singularity inspect ubuntu.img
119+
{
120+
"SINGULARITY_DEFFILE_BOOTSTRAP": "docker",
121+
"SINGULARITY_DEFFILE": "Singularity",
122+
"SINGULARITY_BOOTSTRAP_VERSION": "2.2.99",
123+
"SINGULARITY_DEFFILE_FROM": "ubuntu:latest"
124+
}
125+
126+
```
127+
128+
This is the equivalent of both of:
129+
130+
```
131+
$ singularity inspect -l ubuntu.img
132+
$ singularity inspect --labels ubuntu.img
133+
```
134+
135+
136+
137+
### Runscript
138+
The commands `--runscript` or `-r` will show you the runscript, which also can be shown in `--json`:
139+
140+
```
141+
$ singularity inspect -r -j ubuntu.img{
142+
"data": {
143+
"attributes": {
144+
"runscript": "#!/bin/sh\n\nexec /bin/bash \"$@\""
145+
},
146+
"type": "container"
147+
}
148+
}
149+
```
150+
151+
or in a human friendly, readable print to the screen:
152+
153+
```
154+
$ singularity inspect -r ubuntu.img
155+
156+
##runscript
157+
#!/bin/sh
158+
159+
exec /bin/bash "$@"
160+
```
161+
162+
163+
### Environment
164+
The commands `--environment` and `-e` will show you the container's environment, again specified by the `%environment` section of a bootstrap file, and other `ENV` labels that might have come from a Docker import. You can again choose to see `--json`:
165+
166+
```
167+
$ singularity inspect -e --json ubuntu.img
168+
{
169+
"data": {
170+
"attributes": {
171+
"environment": "# Custom environment shell code should follow\n\n"
172+
},
173+
"type": "container"
174+
}
175+
}
176+
177+
```
178+
or human friendly:
179+
180+
```
181+
$ singularity inspect -e ubuntu.img
182+
183+
##environment
184+
# Custom environment shell code should follow
185+
```
186+
187+
The container in the example above did not have any custom environment variables set.
188+
189+
### Test
190+
The equivalent `--test` or `-t` commands will print any test defined for the container, which comes from the `%test` section of the bootstrap specification Singularity file. Again, we can ask for `--json` or human friendly (default):
191+
192+
```
193+
$ singularity --inspect -t --json ubuntu.img
194+
{
195+
"data": {
196+
"attributes": {
197+
"test": null
198+
},
199+
"type": "container"
200+
}
201+
}
202+
203+
$ singularity inspect -t ubuntu.img
204+
{
205+
"status": 404,
206+
"detail": "This container does not have any tests defined",
207+
"title": "Tests Undefined"
208+
}
209+
210+
```
211+
212+
### Deffile
213+
Want to know where your container came from? You can see the entire Singularity definition file, if the container was created with a bootstrap, by using `--deffile` or `-d`:
214+
215+
```
216+
$ singularity inspect -d ubuntu.img
217+
218+
##deffile
219+
Bootstrap:docker
220+
From:ubuntu:latest
221+
```
222+
or with `--json` output.
223+
224+
```
225+
$ singularity inspect -d --json ubuntu.img
226+
{
227+
"data": {
228+
"attributes": {
229+
"deffile": "Bootstrap:docker\nFrom:ubuntu:latest\n"
230+
},
231+
"type": "container"
232+
}
233+
}
234+
235+
```
236+
237+
The goal of these commands is to bring more transparency to containers, and to help better integrate them into common workflows by having them expose their guts to the world! If you have feedback for how we can improve or amend this, please <a href="https://github.com/singularityware/singularity/issues" target="_blank">let us know!</a>
238+

0 commit comments

Comments
 (0)