github.com/circular-dark/docker@v1.7.0/docs/articles/dsc.md (about)

     1  <!--[metadata]>
     2  +++
     3  title = "PowerShell DSC Usage"
     4  description = "Using DSC to configure a new Docker host"
     5  keywords = ["powershell, dsc, installation, usage, docker,  documentation"]
     6  [menu.main]
     7  parent = "smn_win_osx"
     8  +++
     9  <![end-metadata]-->
    10  
    11  # Using PowerShell DSC
    12  
    13  Windows PowerShell Desired State Configuration (DSC) is a configuration
    14  management tool that extends the existing functionality of Windows PowerShell.
    15  DSC uses a declarative syntax to define the state in which a target should be
    16  configured. More information about PowerShell DSC can be found at
    17  [http://technet.microsoft.com/en-us/library/dn249912.aspx](http://technet.microsoft.com/en-us/library/dn249912.aspx).
    18  
    19  ## Requirements
    20  
    21  To use this guide you'll need a Windows host with PowerShell v4.0 or newer.
    22  
    23  The included DSC configuration script also uses the official PPA so
    24  only an Ubuntu target is supported. The Ubuntu target must already have the
    25  required OMI Server and PowerShell DSC for Linux providers installed. More
    26  information can be found at [https://github.com/MSFTOSSMgmt/WPSDSCLinux](https://github.com/MSFTOSSMgmt/WPSDSCLinux).
    27  The source repository listed below also includes PowerShell DSC for Linux
    28  installation and init scripts along with more detailed installation information.
    29  
    30  ## Installation
    31  
    32  The DSC configuration example source is available in the following repository:
    33  [https://github.com/anweiss/DockerClientDSC](https://github.com/anweiss/DockerClientDSC). It can be cloned with:
    34  
    35      $ git clone https://github.com/anweiss/DockerClientDSC.git
    36  
    37  ## Usage
    38  
    39  The DSC configuration utilizes a set of shell scripts to determine whether or
    40  not the specified Docker components are configured on the target node(s). The
    41  source repository also includes a script (`RunDockerClientConfig.ps1`) that can
    42  be used to establish the required CIM session(s) and execute the
    43  `Set-DscConfiguration` cmdlet.
    44  
    45  More detailed usage information can be found at
    46  [https://github.com/anweiss/DockerClientDSC](https://github.com/anweiss/DockerClientDSC).
    47  
    48  ### Install Docker
    49  The Docker installation configuration is equivalent to running:
    50  
    51  ```
    52  apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys\
    53  36A1D7869245C8950F966E92D8576A8BA88D21E9
    54  sh -c "echo deb https://get.docker.com/ubuntu docker main\
    55  > /etc/apt/sources.list.d/docker.list"
    56  apt-get update
    57  apt-get install lxc-docker
    58  ```
    59  
    60  Ensure that your current working directory is set to the `DockerClientDSC`
    61  source and load the DockerClient configuration into the current PowerShell
    62  session
    63  
    64  ```powershell
    65  . .\DockerClient.ps1
    66  ```
    67  
    68  Generate the required DSC configuration .mof file for the targeted node
    69  
    70  ```powershell
    71  DockerClient -Hostname "myhost"
    72  ```
    73  
    74  A sample DSC configuration data file has also been included and can be modified
    75  and used in conjunction with or in place of the `Hostname` parameter:
    76  
    77  ```powershell
    78  DockerClient -ConfigurationData .\DockerConfigData.psd1
    79  ```
    80  
    81  Start the configuration application process on the targeted node
    82  
    83  ```powershell
    84  .\RunDockerClientConfig.ps1 -Hostname "myhost"
    85  ```
    86  
    87  The `RunDockerClientConfig.ps1` script can also parse a DSC configuration data
    88  file and execute configurations against multiple nodes as such:
    89  
    90  ```powershell
    91  .\RunDockerClientConfig.ps1 -ConfigurationData .\DockerConfigData.psd1
    92  ```
    93  
    94  ### Images
    95  Image configuration is equivalent to running: `docker pull [image]` or
    96  `docker rmi -f [IMAGE]`.
    97  
    98  Using the same steps defined above, execute `DockerClient` with the `Image`
    99  parameter and apply the configuration:
   100  
   101  ```powershell
   102  DockerClient -Hostname "myhost" -Image "node"
   103  .\RunDockerClientConfig.ps1 -Hostname "myhost"
   104  ```
   105  
   106  You can also configure the host to pull multiple images:
   107  
   108  ```powershell
   109  DockerClient -Hostname "myhost" -Image "node","mongo"
   110  .\RunDockerClientConfig.ps1 -Hostname "myhost"
   111  ```
   112  
   113  To remove images, use a hashtable as follows:
   114  
   115  ```powershell
   116  DockerClient -Hostname "myhost" -Image @{Name="node"; Remove=$true}
   117  .\RunDockerClientConfig.ps1 -Hostname $hostname
   118  ```
   119  
   120  ### Containers
   121  Container configuration is equivalent to running:
   122  
   123  ```
   124  docker run -d --name="[containername]" -p '[port]' -e '[env]' --link '[link]'\
   125  '[image]' '[command]'
   126  ```
   127  or
   128  
   129  ```
   130  docker rm -f [containername]
   131  ```
   132  
   133  To create or remove containers, you can use the `Container` parameter with one
   134  or more hashtables. The hashtable(s) passed to this parameter can have the
   135  following properties:
   136  
   137  - Name (required)
   138  - Image (required unless Remove property is set to `$true`)
   139  - Port
   140  - Env
   141  - Link
   142  - Command
   143  - Remove
   144  
   145  For example, create a hashtable with the settings for your container:
   146  
   147  ```powershell
   148  $webContainer = @{Name="web"; Image="anweiss/docker-platynem"; Port="80:80"}
   149  ```
   150  
   151  Then, using the same steps defined above, execute
   152  `DockerClient` with the `-Image` and `-Container` parameters:
   153  
   154  ```powershell
   155  DockerClient -Hostname "myhost" -Image node -Container $webContainer
   156  .\RunDockerClientConfig.ps1 -Hostname "myhost"
   157  ```
   158  
   159  Existing containers can also be removed as follows:
   160  
   161  ```powershell
   162  $containerToRemove = @{Name="web"; Remove=$true}
   163  DockerClient -Hostname "myhost" -Container $containerToRemove
   164  .\RunDockerClientConfig.ps1 -Hostname "myhost"
   165  ```
   166  
   167  Here is a hashtable with all of the properties that can be used to create a
   168  container:
   169  
   170  ```powershell
   171  $containerProps = @{Name="web"; Image="node:latest"; Port="80:80"; `
   172  Env="PORT=80"; Link="db:db"; Command="grunt"}
   173  ```