builds import-image

Import a prebuilt container image into a new Build. The Rack pulls the image from the source registry (using skopeo) and pushes it to the Rack's internal registry. A Release is created automatically on success.

This command requires a convox.yml manifest to define the App's Services. By default it reads convox.yml from the current directory.

When the source image is a multi-architecture index, the platform the Rack copies depends on the Rack and the App. The first matching row applies:

Rack and App	Platform copied
AWS Rack with Karpenter enabled that builds multi-architecture images, or, from Rack version 3.25.9, whose node_type (or build_node_type with build_node_enabled=true) is a different architecture from karpenter_arch	Every platform the index publishes, whatever BuildArch is
App with BuildArch set, on Rack version 3.25.12 or later	linux/<BuildArch>
Any other App	The architecture of the node running the Rack API

A source image published for a single platform is copied as it is, whatever BuildArch is, and its Processes fail with an exec format error on nodes of another architecture. A multi-architecture source that does not publish the BuildArch platform fails the import. An invalid BuildArch value fails the import before any image is copied, with invalid BuildArch: x86, must be amd64 or arm64. See Architecture Selection and Mixed-Architecture Racks.

Usage

    convox builds import-image <source-image>

Flags

Flag	Short	Description
--rack	-r	Rack name
--app	-a	App name
--manifest	-m	Path to convox.yml manifest (default: convox.yml)
--src-creds-user		Source registry username
--src-creds-pass		Source registry password (deprecated; use --src-creds-pass-env or --src-creds-pass-stdin)
--src-creds-pass-env		Read source registry password from the named environment variable
--src-creds-pass-stdin		Read source registry password from stdin (single line)

Only one of --src-creds-pass, --src-creds-pass-env, or --src-creds-pass-stdin may be specified. The --src-creds-pass flag is deprecated because it exposes credentials in process listings. It still works and prints a warning; use --src-creds-pass-env or --src-creds-pass-stdin instead.

Examples

Import a public image:

    $ convox builds import-image registry.example.com/myapp:v1.2.3 -a myapp
    Creating build... OK, BABCDEFGHIJ
    Relaying image registry.example.com/myapp:v1.2.3... OK
    Waiting for import to complete... OK
    Creating release... OK, RABCDEFGHIJ
    Build:   BABCDEFGHIJ
    Release: RABCDEFGHIJ

Import from a private registry using an environment variable for credentials:

    $ export REGISTRY_PASS=my-secret-token
    $ convox builds import-image registry.example.com/myapp:v1.2.3 -a myapp \
        --src-creds-user myuser \
        --src-creds-pass-env REGISTRY_PASS
    Creating build... OK, BABCDEFGHIJ
    Relaying image registry.example.com/myapp:v1.2.3... OK
    Waiting for import to complete... OK
    Creating release... OK, RABCDEFGHIJ
    Build:   BABCDEFGHIJ
    Release: RABCDEFGHIJ

Import from a private registry using stdin for credentials:

    $ echo "$REGISTRY_PASS" | convox builds import-image registry.example.com/myapp:v1.2.3 -a myapp \
        --src-creds-user myuser \
        --src-creds-pass-stdin

Use a custom manifest path:

    $ convox builds import-image registry.example.com/myapp:v1.2.3 -a myapp -m deploy/convox.yml

See Also

• builds for listing, exporting, and inspecting Builds
• Build for Build concepts and build arguments
• deploy for building and promoting in one step
• registries for managing external registry credentials