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 Rack copies the image for the architecture of the node running the Rack API. It copies every platform the index publishes on an AWS Rack with Karpenter enabled that builds multi-architecture images, and from Rack version 3.25.9 on an AWS Karpenter Rack whose node_type, or build_node_type with build_node_enabled=true, is a different architecture from karpenter_arch. A source image published for a single platform is copied as it is. 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