Skip to content

acalv/docker-formula

 
 

Repository files navigation

Docker

Travis CI Build Status Semantic Release

Formulas for working with Docker

See the full SaltStack Formulas installation and usage instructions.

If you are interested in writing or contributing to formulas, please pay attention to the Writing Formula Section.

If you want to use this formula, please pay attention to the FORMULA file and/or git tag, which contains the currently released version. This formula is versioned according to Semantic Versioning.

See Formula Versioning Section for more details.

Commit message formatting is significant!!

Please see How to contribute for more details.

Install and run Docker daemon

Note

On Ubuntu 12.04 state will also update kernel if needed (as mentioned in docker installation docs). You should manually reboot minions for kernel update to take affect.

You can override the default docker daemon options by setting each line in the "docker-pkg:lookup:config" pillar. This effectively writes the config in /etc/default/docker. See pillar.example

Pulls and runs a number of docker containers with arbitrary run options all configurable via pillars. Salt includes dockerio and dockerng states, but both depend on docker-py library, which not always implements the latest docker run options. This gives the user more control over the docker run options, but it doesn't try to implement all the other docker commands, such as build, ps, inspect, etc. It just pulls an image and runs it.

To use it, just include docker.containers in your top.sls, and configure it using pillars:

docker-containers:
  lookup:
    mycontainer:
      image: "my_image"
      cmd:
      runoptions:
        - "-e MY_ENV=warn"
        - "--log-driver=syslog"
        - "-p 2345:2345"
        - "--rm"
    myapp:
      image: "myregistry.com:5000/training/app:3.0"
      args:
        - "https://someargument_as_an_url"
        - "--port 5500"
      cmd:  python app.py
      runoptions:
        - "--log-driver=syslog"
        - "-v /mnt/myapp:/myapp"
        - "-p 80:80"
        - "--rm"
      stopoptions:
        - -t 60

In the example pillar above:

  • mycontainer and myapp are the container names (ie --name option).
  • Upstart files are created for each container, so service <container_name> stop|start|status should just work
  • service <container_name> stop will wipeout the container completely (ie docker stop <container_name> + docker rm <container_name>)

Stop Docker daemon and remove older docker packages (usually called 'docker' and 'docker-engine'). Linux only.

Configures the upstream docker's repo (true, by default).

Installs Docker Desktop for Mac.

Installs Docker Desktop for Mac.

Installs Docker Compose (previously fig) to define groups of containers and their relationships with one another. Use docker.compose-ng to run docker-compose.

The intent is to provide an interface similar to the specification provided by docker-compose. The hope is that you may provide pillar data similar to that which you would use to define services with docker-compose. The assumption is that you are already using pillar data and salt formulae to represent the state of your existing infrastructure.

No real effort had been made to support every possible feature of docker-compose. Rather, we prefer the syntax provided by the docker-compose whenever it is reasonable for the sake of simplicity.

It is worth noting that we have added one attribute which is decidedly absent from the docker-compose specification. That attribute is dvc. This is a boolean attribute which allows us to define data only volume containers which can not be represented with the docker.running state interface since they are not intended to include a long living service inside the container.

See the included pillar.example for a representative pillar data block.

To use this formula, you might target a host with the following pillar:

docker:
  compose:
    registry-data:
      dvc: True
      image: &registry_image 'library/registry:0.9.1'
      container_name: &dvc 'registry-999-99-data'
      command: echo *dvc data volume container
      volumes:
        - &datapath '/registry'
    registry-service:
      image: *registry_image
      container_name: 'registry-999-99-service'
      restart: 'always'
      volumes_from:
        - *dvc
      environment:
        SETTINGS_FLAVOR: 'local'
        STORAGE_PATH: *datapath
        SEARCH_BACKEND: 'sqlalchemy'
    nginx:
      image: 'library/nginx:1.9.0'
      container_name: 'nginx-999-99'
      restart: 'always'
      links:
        - 'registry-999-99-service:registry'
      ports:
        - '80:80'
        - '443:443'

Then you would target a host with the following states:

include:
  - base: docker
  - base: docker.compose-ng

NEW:

Since the more generic docker-container above has been implemented, the docker-registry state can now be deprecated. The registry is just another docker image, we can use docker-container with a pillar similar to this:

docker-containers:
  lookup:
    registry:
      image: "registry:2"
      cmd:
      runoptions:
        - "-e REGISTRY_STORAGE=s3"
        - "-e REGISTRY_STORAGE_S3_REGION=us-west-1"
        - "-e REGISTRY_STORAGE_S3_BUCKET=my-bucket"
        - "-e REGISTRY_STORAGE_S3_ROOTDIRECTORY=my_registry/folder"
        - "--log-driver=syslog"
        - "-p 5000:5000"
        - "--rm"

OLD:

IMPORTANT: docker.registry will eventually be removed.

Run a Docker container to start the registry service.

If "registry:lookup:version" pillar is either the string "latest" or not specified at all, it defaults to the "latest" image tag, which at the time of this writing is still pointing to 0.9.1, even though 2.x is out for a while. It still uses the old registry pillar configuration for backwards compatibility. See the commented out block in pillar.example

If "registry:lookup:version" is set to any other version, e.g. 2, an image with that tag will be downloaded and the new pillar configuation should be used. See pillar.example.

In this case, extra docker run options can be provided in your "registry:lookup:runoptions" pillar to provide environment variables, volumes, or log configuration to the container.

By default, the storage backend used by the registry is "filesystem". Use environment variables to override that, for example to use S3 as backend storage.

Stop Docker daemon. Remove older docker packages (usually called 'docker' and 'docker-engine').

Note that some of the internal states such as docker.running are references to the internal dockerio states

Linux testing is done with kitchen-salt.

  • Ruby
  • Docker
$ gem install bundler
$ bundle install
$ bin/kitchen test [platform]

Where [platform] is the platform name defined in kitchen.yml, e.g. debian-9-2019-2-py3.

Creates the docker instance and runs the template main state, ready for testing.

Runs the inspec tests on the actual instance.

Removes the docker instance.

Runs all of the stages above in one go: i.e. destroy + converge + verify + destroy.

Gives you SSH access to the instance for manual testing.

Releases

No releases published

Packages

No packages published

Languages

  • SaltStack 63.3%
  • JavaScript 15.8%
  • HTML 9.4%
  • Ruby 8.3%
  • Shell 3.2%