nixos/doc/manual/from_md/administration/declarative-containers.section.xml


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-declarative-containers">
  <title>Declarative Container Specification</title>
  <para>
    You can also specify containers and their configuration in the
    host’s <literal>configuration.nix</literal>. For example, the
    following specifies that there shall be a container named
    <literal>database</literal> running PostgreSQL:
  </para>
  <programlisting language="bash">
containers.database =
  { config =
      { config, pkgs, ... }:
      { services.postgresql.enable = true;
      services.postgresql.package = pkgs.postgresql_10;
      };
  };
</programlisting>
  <para>
    If you run <literal>nixos-rebuild switch</literal>, the container
    will be built. If the container was already running, it will be
    updated in place, without rebooting. The container can be configured
    to start automatically by setting
    <literal>containers.database.autoStart = true</literal> in its
    configuration.
  </para>
  <para>
    By default, declarative containers share the network namespace of
    the host, meaning that they can listen on (privileged) ports.
    However, they cannot change the network configuration. You can give
    a container its own network as follows:
  </para>
  <programlisting language="bash">
containers.database = {
  privateNetwork = true;
  hostAddress = &quot;192.168.100.10&quot;;
  localAddress = &quot;192.168.100.11&quot;;
};
</programlisting>
  <para>
    This gives the container a private virtual Ethernet interface with
    IP address <literal>192.168.100.11</literal>, which is hooked up to
    a virtual Ethernet interface on the host with IP address
    <literal>192.168.100.10</literal>. (See the next section for details
    on container networking.)
  </para>
  <para>
    To disable the container, just remove it from
    <literal>configuration.nix</literal> and run
    <literal>nixos-rebuild switch</literal>. Note that this will not
    delete the root directory of the container in
    <literal>/var/lib/containers</literal>. Containers can be destroyed
    using the imperative method:
    <literal>nixos-container destroy foo</literal>.
  </para>
  <para>
    Declarative containers can be started and stopped using the
    corresponding systemd service, e.g.
    <literal>systemctl start container@database</literal>.
  </para>
</section>