# Migrating existing third party containers

## Converting from Starlark dictionaries to `third_party_container_dep` rules

All existing third party containers that live in Starlark dictionaries will
need to be migrated to the new `third_party_container_dep` rules.

To migrate existing dictionaries:

1. Take an existing dictionary in an `images.bzl` file like:

    ```python
    IMAGES = {
        "alpine-new": {
            "DIGEST": "sha256:abcdef12345iamarealsha",
            "REPO": "path/to/alpine",
            "REGISTRY": "gcr.io",
        },
        "ubuntu-new": {
            "TAG": "v10.0",
            "DIGEST": "sha256:abcdef12345iamarealsha",
            "REPO": "path/to/ubuntu",
            "REGISTRY": "gcr.io",
        }
    }
    ```

1. Like in the base documentation, create a new function to wrap the
dependencies:
`images.bzl`

    ```python
    load("//hack/build/rules/container:third_party_images.bzl", "third_party_container_dep")

    def my_images():
        # deps go here
    ```

1. For each dictionary item, substitute each value into the corresponding
fields in the `third_party_container_dep` rule:  
**NOTES:**

    - The key of the dictionary (`alpine-new` for example) must have its `-`'s
    replaced with `_` (`alpine_new`) when moving to the `image_name` field in
    `third_party_container_dep`. There is a guard in the `third_party_container_dep`
    rule that will error if not formatted correctly.
    - Existing references to constants like `MY_REGISTRY` can be used for the
    corresponding rule value.
    - Unfortunately, anything besides constants cannot be resolved by the Gazelle
    plugin, for example `format()` string functions. Feel free to reach out to the
    foundation team for assistance if needed.

    `images.bzl`

    ```python
    load("//hack/build/rules/container:third_party_images.bzl", "third_party_container_dep")
    load("//:constants.bzl", "MY_REGISTRY")

    def my_images():
        third_party_container_dep(
            image_name = "alpine_new",
            digest = "sha256:abcdef12345iamarealsha",
            repository = "path/to/alpine",
            registry = "gcr.io",
        )
        third_party_container_dep(
            image_name = "ubuntu_new",
            tag = "v10.0",
            digest = "sha256:abcdef12345iamarealsha",
            repository = "path/to/ubuntu",
            registry = MY_REGISTRY,
        )
    ```

1. Once you have replaced the dictionary items with rules, add your new function
to the `hack/deps/images.bzl` file:

    ```python
    load("//path/to:my_images.bzl", "my_images")

    def third_party_images():
        base_images()
        calico_images()
        # your new function here
        my_images()
    ```