commit db9f3a1bd6406974a28832c57da276360f50a948 Author: Roman Gorshunov Date: Thu Apr 23 17:05:33 2020 +0200 Add container image and Dockerfile conventions Change-Id: I995816bafac0c95fae0618efc239d93f4069d642 diff --git a/.gitignore b/.gitignore index f4b14d2..ded56fc 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,3 @@ -naries for programs and plugins *.exe *.exe~ *.dll diff --git a/doc/examples/Dockerfile.opensuse_15 b/doc/examples/Dockerfile.opensuse_15 new file mode 100644 index 0000000..490da64 --- /dev/null +++ b/doc/examples/Dockerfile.opensuse_15 @@ -0,0 +1,56 @@ +# Simplified example Dockerfile.opensuse_15 +ARG FROM=opensuse/leap:15.1 +FROM ${FROM} as builder + +ENV LC_ALL=C.UTF-8, LANG=C.UTF-8 + +# Don't run 'zypper up', 'apt-get upgrade' and similar. List packages +# being installed in alphabetical order to avoid possible merge +# conflicts and make it easy to read. Indent commands with spaces. +RUN set -ex && \ + mkdir -p /armada && \ + zypper refresh && \ + zypper --non-interactive install \ + ca-certificates \ + curl \ + gcc \ + git \ + libopenssl-devel \ + make \ + netcfg \ + python3 \ + python3-devel \ + python3-pip \ + python3-setuptools \ + tar + +# ... + +ARG FROM=opensuse/leap:15.1 +FROM ${FROM} + +LABEL org.opencontainers.image.authors='airship-discuss@lists.airshipit.org, irc://#airshipit@freenode' \ + org.opencontainers.image.url='https://airshipit.org' \ + org.opencontainers.image.documentation='https://airship-armada.readthedocs.org' \ + org.opencontainers.image.source='https://opendev.org/airship/armada' \ + org.opencontainers.image.vendor='The Airship Authors' \ + org.opencontainers.image.licenses='Apache-2.0' + +ENV LC_ALL=C.UTF-8, LANG=C.UTF-8, UID=1000, GID=1000 + +ENTRYPOINT ["./entrypoint.sh"] +CMD ["server"] + +COPY --from=builder /armada . + +RUN useradd -u ${UID} -g ${GID} -d /armada airship + +RUN set -ex && \ + zypper refresh && \ + zypper --non-interactive install \ + ca-certificates \ + python3 + +# ... + +USER airship diff --git a/doc/source/develop/code-conventions.rst b/doc/source/develop/code-conventions.rst index db55253..625cbd7 100644 --- a/doc/source/develop/code-conventions.rst +++ b/doc/source/develop/code-conventions.rst @@ -45,21 +45,72 @@ and follow the standards documented there. Images ~~~~~~ -Each project that creates a `Docker`_ image will keep the dockerfile in a +Each project that creates `Docker`_ images will keep Dockerfiles in a directory ``images`` located at the root of the project. The images directory will contain subdirectories for each of the images created as part of that -project. The subdirectory will contain the dockerfile that can be used to -generate the image. +project. The subdirectory will contain Dockerfiles that can be used to +generate images. E.g.: For project ``foo``, which also produces a Docker image for ``bar``: -- foo/images/foo contains the dockerfile for ``foo`` -- foo/images/bar contains the dockerfile for ``bar`` +- foo/images/foo contains Dockerfiles for ``foo`` +- foo/images/bar contains Dockerfiles for ``bar`` + +Each image must include the following set of labels conforming to the +`OCI image annotations standard`_ as the minimum: + +:: + + org.opencontainers.image.authors='airship-discuss@lists.airshipit.org, irc://#airshipit@freenode' + org.opencontainers.image.url='https://airshipit.org' + org.opencontainers.image.documentation='' + org.opencontainers.image.source='' + org.opencontainers.image.vendor='The Airship Authors' + org.opencontainers.image.licenses='Apache-2.0' + org.opencontainers.image.revision='' + org.opencontainers.image.created='UTC date and time in RFC3339 format with seconds' + org.opencontainers.image.title='' + +Last three annotations (revision, created and title), being dynamic, are +added on a container build stage. Others are statically defined in +Dockerfiles. Optional custom ``org.airshipit.build=community`` annotation is +added to the Airship images published to the community. + +Image tags must follow format: + +- ``:_`` +- ``:_`` - latest image built from specific branch +- ``:latest_`` - latest image built from master + +The ``_`` (e.g. ``_ubuntu_xenial``) could be omitted. See +`Airship Multiple Linux Distribution Support`_ specification for details. + +Images should follow best practices for the container images. Be slim and +secure in particular. + +Dockerfile +~~~~~~~~~~ +Dockerfile file names must follow format: ``Dockerfile.``, where +```` matches corresponding image tag suffix. The +``.`` could be omitted where not relevant. + +Lines should be indented by a space character next to the Dockerfile +instruction block they correspond to. + +Dockerfile must allow base image substitution via ``FROM`` argument. This is +to allow the use of base images stored in third-party or internal repositories. + +Dockerfile should follow best practices. Use multistage container builds where +possible to reduce image size and attack surface. ``RUN`` statements should +pass linting via ``shellcheck``. You may use available Dockerfile linters, if +you wish to do so. + +See `example Dockerfile`_ file for reference. Makefile ~~~~~~~~ -Each project must provide a makefile at the root of the project. The makefile -should implement each of the following makefile targets: +Each project must provide a Makefile at the root of the project. The Makefile +should implement each of the following Makefile targets: - ``images`` will produce the docker images for the component and each other component it is responsible for building. @@ -82,7 +133,7 @@ should implement each of the following makefile targets: code language (e.g. Python for armada and Go for airshipctl) as listed in the Linting and Formatting Standards. -For projects that are Python based, the makefile targets typically reference +For projects that are Python based, the Makefile targets typically reference tox commands, and those projects will include a tox.ini defining the tox targets. Note that tox.ini files will reside inside the source directories for modules within the project, but a top-level tox.ini may exist at the root of @@ -90,7 +141,7 @@ the repository that includes the necessary targets to build documentation. Documentation ~~~~~~~~~~~~~ -Also see :ref:`documentation-conventions` +Also see :ref:`documentation-conventions`. Documentation source for the component should reside in a 'docs' directory at the root of the project. @@ -298,3 +349,6 @@ prevail. .. _ansible-lint: https://github.com/ansible/ansible-lint .. _markdownlint: https://github.com/DavidAnson/markdownlint .. _Shellcheck: https://github.com/koalaman/shellcheck +.. _OCI image annotations standard: https://github.com/opencontainers/image-spec/blob/master/annotations.md#annotations +.. _Airship Multiple Linux Distribution Support: https://airship-specs.readthedocs.io/en/latest/specs/1.x/approved/airship_multi_linux_distros.html#container-builds +.. _example Dockerfile: https://opendev.org/airship/docs/src/branch/master/examples/Dockerfile.opensuse_15