import directive is deprecated and replaced by imports.

[smoser]

Deprecation of import directive

The import directive in stacker.yaml files is deprecated. It is replaced by imports (plural).

Support for import will not be present in any stacker release made after 2025-01-01.

The import directive contained all the functionality of the imports directive in stacker releases up until 0.4.0 and initial release of the 1.0 branch. 1.0 pre-releases contain a warning on use of import. Users must migrate to imports directive.

Migration path

In order to change from import to imports the user will:

1. change use of import in stacker.yaml files to imports
2. change reference to imported items from within a run section from /stacker/<path> to /stacker/imports/<path>.

As an example, consider this old stacker-old.yaml file:

build:
  from:
    type: docker
    url: ${{DOCKER_BASE:docker://}}busybox:latest
  build_only: true
  import:
    - path: tools/fizz-buzz
    - path: tools/frobnicator
      dest: /opt/bin/frobnicator
      perms: 0755
  run: |
    cp /stacker/fizz-buzz /opt/bin/fizz-buzz
    chmod 755 /opt/bin/fizz-buzz

Building the above stacker-old.yaml file will give a deprecation warning.
To use imports, the new stacker.yaml would look like this:

build:
  from:
    type: docker
    url: ${{DOCKER_BASE:docker://}}busybox:latest
  build_only: true
  imports:
    - path: tools/fizz-buzz
    - path: tools/frobnicator
      dest: /opt/bin/frobnicator
      perms: 0755
  run: |
    cp /stacker/imports/fizz-buzz /opt/bin/fizz-buzz
    chmod 755 /opt/bin/fizz-buzz

The changes are highlighted in this diff:

@@ -3,11 +3,11 @@
     type: docker
     url: ${{DOCKER_BASE:docker://}}busybox:latest
   build_only: true
-  import:
+  imports:
     - path: tools/fizz-buzz
     - path: tools/frobnicator
       dest: /opt/bin/frobnicator
       mode: 0755
   run: |
-    cp /stacker/fizz-buzz /opt/bin/fizz-buzz
+    cp /stacker/imports/fizz-buzz /opt/bin/fizz-buzz
     chmod 755 /opt/bin/fizz-buzz

Reason for change

The reason behind the change from import to imports was to be consistent with other stacker top level directives that contained a dictionary or list (binds, labels).

The more invasive change of /stacker to /stacker/imports was necessary to provide a clean namespace for stacker inside a container during layer build. As stacker grew more functionality, it needed to be able to utilize the /stacker namespace safely without colliding with user-provided input. With user provided paths in /stacker, this was not possible.

As an example of this, stacker now creates /stacker/bin/ directory for its own use. If a user's stacker.yaml file included an import of bin/, then stacker would collide on that namespace. Rather than put restrictions on filenames or paths that a user could import, stacker confines those imports to /stacker/imports and gives the user full control of that namespace.