imgpkg init Command

[danielhelfand]

Describe the problem/challenge you have

When first creating a Bundle with imgpkg, I would like the ability to generate all the contents of the .imgpkg directory with a single command. I would like to use this command directly through imgpkg and not directly use an additional tool such as kbld.

Describe the solution you'd like

imgpkg init -f /files creates the ImagesLock and Bundle metadata config in the .imgpkg directory.

Where applicable, we should consider allowing the user to have options to fill in the properties of the bundle metadata file.

imgpkg init -f /files --name my-bundle

Anything else you would like to add:

The behavior in this case could be calling out to kbld to generate the ImagesLock file as a sensible default.

[joaopapereira]

Since I started using the imgpkg I feel like we are missing a init command to help bootstrap a bundle. I do have some questions:

1. If the user does not provide metadata for the bundle should we create the bundle.yml file?
2. If the user provides some metadata what is the minimum information we would require to create a bundle.yml file?
3. Not a fan of creating a dependency between imgpkg and kbld. Nevertheless imgpkg does not have a way to pre-populate the images.yml file. What if we asked the user to provide the file something like imgpkg init -f my/configuration/files --image-lock /images/i/want/in/my/bundle/images.yml? If the user did not provide the file we would create the .imgpkg/images.yml file with just the skeleton.

[danielhelfand]

To maybe repurpose/simplify, the original design docs call for initializing a bundle directory (i.e. .imgpkg).

If the user does not provide metadata for the bundle should we create the bundle.yml file? If the user provides some metadata what is the minimum information we would require to create a bundle.yml file?

Not sure if populating that directory with empty files like the bundle metadata would be valuable to end users. In thinking this over a bit more, there needs to be more discussion on use cases for the bundle metadata file before it becomes a core part of an imgpkg command.

What if we asked the user to provide the file something like imgpkg init -f my/configuration/files --image-lock /images/i/want/in/my/bundle/images.yml?

I think this approach would be great, but there is the design question of how kbld already provides this behavior. I agree that adding a dependency between kbld and imgpkg is a not great pattern.

What might be best is to close this issue and turn it into a discussion first, or try to better understand what the original intent was behind what is documented in the original proposal.

[ewrenn8]

imgpkg init -f my/configuration/files --image-lock /images/i/want/in/my/bundle/images.yml

At this point, we may as well just add the ability for push to generate the imgpkg dir for you if you specify an images lock, instead of making this a whole new command.

The initial intent of init was to set up a space on disk that is an empty bundle, sort of like git init. It would not create nor push a bundle. This would give the user the correct directory structure with empty metadata files (BundleLock and ImageLock) that they can fill in however they want, or leave empty if they just want to satisfy push's requirements. It would save the user the effort to create the directory, fill it in with properly structured yaml, etc

Tangentially, I wonder if supporting something like a .imgpkgignore on push would make sense. Then users could do something like:

1. imgpkg init
2. create vendir file
3. vendir sync
4. kbld for lock files if needed
5. then imgpkg push (with vendir files in .imgpkgignore if they dont want to include them)

[joaopapereira]

@ewrenn8 I like the workflow that you are suggesting, where init would just create the folder structure and eventually the images.yml empty or we could provide a flag that would point to a file that contains the images lock file and we would just copy it into place. something like this: imgpkg init --images-lock /tmp/images.yml

The Idea of an ignore is also interesting and can be an addon that we could provide to this init command in time.

@danielhelfand as per your point I think that we should bring this up in our community meeting so that we can come to a consensus.

[danielhelfand]

Was thinking about this a bit more and am wondering if some type of plugin model might make sense for an imgpkg init command. This would allow a user to specify what tool to use or a script in order to generate the ImagesLock and also create the .imgpkg directory.

Through an env variable or through something via the imgpkg init command, a user could specify what to shell out to when generating the lock file:

export IMGPKG_INIT=kbkd
imgpkg init -f manifests/

imgpkg init -f manifests/ --lock-generator kbld

[joaopapereira]

The generator is an interesting idea, nevertheless, this would require imgpkg to understand how to call kbld to generate this lock file, and in the future when we would like to introduce a new lock generator we would have to add some specific logic for it. This is not unheard of since we do something very similar with kbld.

[github-actions[bot]]

This issue is being marked as stale due to a long period of inactivity and will be closed in 5 days if there is no response.

[pivotaljohn]

This seems like a viable idea that is in the midst of discussion: adjusted labels accordingly.

[joaopapereira]

I am going to accept this issue. For now, I think we should start with the --lock-generator flag and the implementation needed to use kbld as the first generator.

Notes:

• kbld should not be embedded in imgpkg (imgpkg should call the kbld binary to do the work)
• Do we need to provide a path where we want to initialize the bundle? something like imgpkg init -f manifests -o . --lock-generator kbld?

[gcheadle-vmware]

Introduce the imgpkg init command

As a user, I want to be able to bootstrap the process of pushing a bundle by using the init command. The imgpkg init -f command will generate an .imgpkg directory in the provided directory. This .imgpkg dir will contain and ImagesLock file filled with empty values for the images. Besides the -f flag, which denotes the root of the bundle, the one optional flag for the imgpkg init command is --lock-generator, which specifies the generation of the ImagesLock file.

---

🟢 Scenario 1: imgpkg init -f

As an imgpkg user wanting to prepare and push a bundle, when I run imgpkg init -f ., I want imgpkg to create and check the minimum requirements to make my configuration in the current directory a bundle, So that when I list all files in the current directory (ls -a .), I see an .imgpkg/images.yml file with no listed images.

---

🟢 Scenario 2: imgpkg init -f <> --lock-generator kbld

As an imgpkg user wanting to prepare and push a bundle with an images lock file, when I run imgpkg init -f staging-app --lock-generator kbld, I want imgpkg to create an ImagesLock file using the files provided via -f and the kbld binary (provided by the user), And create/check the minimum requirements to make my configuration a bundle, So that when I list all files in the "staging-app" directory (ls -a staging-app), I see an .imgpkg/images.yml file with all dependent images detected by kbld.

---

🛑 Scenario 3: imgpkg init -f <> --lock-generator anythingElse

As an imgpkg user trying to bootstrap pushing bundle with an images lock file, when I run imgpkg init -f . --lock-generator imgpkg, I want imgpkg to give an error, lightly explaining what a lock generator is and lists the options (just kbld at the moment) So that when I try again, I know what lock generators I can use and how to use them.

---

Future considerations for this command:

• Add flags to populate/create fields in the bundle metadata file that may exist in the .imgpkg directory.
• Add the recognition of a .imgpkgignore file/dir that would also get created during imgpkg init