# Package Authoring
## TCE Package Authoring

### Scenario 1: upstream config + imgpkg bundle + ytt

Rules followed here:
1. Lines without indentation is what will be asked to user.
2. Lines with #, will be the output which user will see, while following along. Actual output will not have `#`
3. Lines with <> will be the actual commands which will be run by the CLI.
4. Have targeted the most common use case here.

### Update Scenario:
1. Release tag change
2. Paths change
3. Just update the version
4. ytt files change

roaggarwal:~$ kctrl pkg create pkg-a -d <path>
                OR
roaggarwal:~$ kctrl pkg create pkg-a -f 1.23.0.yml -f metadata.yml                
    # Great. Will be pre loading the values from metadata.yml and 1.23.0.yml
    # Please select the step from which you want to start making the changes.
1. Fetch Configuration type
2. Templating tool types
3. Enter the package version to be used
4. Do you want to specify the values Schema(y/n)
           

roaggarwal:~$ kctrl pkg create pkg-a
        #Lets start off on the package creation for pkg-a
        #First we need a directory to store all configurations
        #Creating directory <DEFAULT_LOC>/pkg-a
        #mkdir -p <DEFAULT_LOC>/pkg-a
        <mkdir -p <DEFAULT_LOC>/pkg-a>
        # Done.
        # Next step is to add the configuration which makes up the package for distribution. Configuration can be fetched from different types of sources. 
Fetch Configuration Types:
1. Imgpkg(recommended)
2. Helm
3. Helm Release
4. Inline
Enter the configuration Type: 1

Is the imgpkg bundle already created(y/n): n
        # Cool, lets create the imgpkg bundle first
        # Creating directory <DEFAULT_LOC>/pkg-a/bundle/config
        # mkdir -p <DEFAULT_LOC>/pkg-a/bundle/config
        <mkdir -p <DEFAULT_LOC>/pkg-a/bundle/config>
        # Creating directory <DEFAULT_LOC>/pkg-a/bundle/config/.imgpkg
        # mkdir -p <DEFAULT_LOC>/pkg-a/bundle/config/.imgpkg
        <mkdir -p <DEFAULT_LOC>/pkg-a/bundle/config/.imgpkg>
        # In Carvel, An upstream source is the location from where we want to sync the software configuration.
        # Different types of upstream are:
Upstream types:
1. Github Release(recommended)
2. HelmChart
3. Image
Enter the upstream type: 1
         
Enter slug for repository(org/repo):
Do you want to use the latest released version(y/n): n
        # Ok. Then we have to mention the specific release tag now which we want to package.
Enter the release tag: 
        # Next step is to enter the manifests paths which makes up the package content.
Does you package encompasses everything mentioned in the github Release(y/n): n
        # Now, we need to enter the specific paths which we want to include as package content.
Enter the paths which needs to be included as part of this package: 
        # We have all the information needed to sync the upstream.
        # Lets create vendir.yaml file with above inputs.
        # cat vendir.yaml
        cat vendir.yaml
        # Next step is to Run vendir to sync the data from github to upstream folder.
        # Running vendir sync --chdir bundle
        vendir sync --chdir bundle
        # To ensure that data has been synced, lets do 
        # ls -l <DEFAULT_LOC>/pkg-a/bundle/config/upstream
        ls -l <DEFAULT_LOC>/pkg-a/bundle/config/upstream
        # after running vendir sync, there is one more file created i.e. bundle/vendir.lock.yml
        # This lock file resolves the release tag to the specific GitHub release and declares that the config is the synchronization target path.
        # Lets see its content
        # cat bundle/vendir.lock.yml
        cat bundle/vendir.lock.yml
        
        # If you wish to use default values, then skip next step. Otherwise, we can use the ytt(a templating and overlay tool) to provide custom values.
Do you want to use ytt as a templating and overlay tool(y/n):y
        
Enter the path where ytt files are located:
        # Copying the ytt files inside the package.
        # cp -r ABOVE_LOCATION <DEFAULT_LOC>/pkg-a/bundle/config
        cp -r ABOVE_LOCATION <DEFAULT_LOC>/pkg-a/bundle/config
        # imgpkg bundle configuration is now complete. Let's use kbld to lock it down.
        # kbld allows to build the imgpkg bundle with immutable image references.
        # kbld scans a package configuration for any references to images and creates a mapping of image tags to a URL with a sha256 digest. 
        # This mapping will then be placed into an images.yml lock file in your bundle/.imgpkg directory.
        # Running kbld --file bundle --imgpkg-lock-output bundle/.imgpkg/images.yml 1>> /dev/null
        kbld --file bundle --imgpkg-lock-output bundle/.imgpkg/images.yml 1>> /dev/null
        # Lets see how the images.yaml file looks like:
        # Running cat bundle/.imgpkg/images.yml
        cat bundle/.imgpkg/images.yml
        
        # Now, we can use Imgpkg to Push the Package to an OCI Registry.
        # imgpkg is another Carvel tool that enables you to package, distribute, and relocate your Kubernetes configuration and OCI images as a bundle.
Do you want to push the bundle to the registry(y/n): y
        # If it is a dockerHub registry, then ensure that you have already done docker login. Otherwise, have the information handy regarding the private registry and login credentials.
Where do you want to push the bundle: 
1. DockerHub
2. Private Registry
Enter: 2
Enter the registry URL: 
Enter the username:
Enter the password:
Do you want to provide the project name to which this bundle belong(default: your org name):
Do you want to provide the tag name(default: latest): 
        # Running imgpkg to push the bundle directory and indicate what project name and tag to give it.
        # imgpkg push --bundle ttl.sh/seemiller/cert-manager:6h --file bundle/
        imgpkg push --bundle ttl.sh/seemiller/cert-manager:6h --file bundle/
        # Always keep a note of where it is pushed to, as this will be needed later . 
        
        
        
Enter the Image URL(here it will be auto populated from the previous step):
        # If it is a image hosted on private repository, then we will need the credentials or token. We expect that you would have already created a secret with those credentials or token. For a public image, we don't need the credentials or the secret name.    
        # Next step is to define which templating tool to be used to render the package template. 
        # A package template can be rendered by various different tools.
Templating tool types:
1. ytt(recommended)
2. helmTemplate
Enter the templating tool to be used: 1
        # We need to provide the values to ytt. They can be done in three different ways:
        # 1. We can specify the additional files(including data values) to be used via ytt
        # 2. We can enter the values directly i.e. inline
        # 3. They can be picked up from the secret or configmap on the K8s cluster
How do you want to template ytt:
1. ytt files location(recommended)
2. inline
3. valuesFrom configMap or secret
Enter the ytt templating option: 1
Enter the location of ytt files: 
        # Next step is to use kbld to resolve the image references to use digest. kbld will resolve the image and store the digest in a images.yml file.
Enter the path where kbld should store the digest(default: .imgpkg/images.yaml): 
        # A package name must be a fully qualified name. 
        # It must consist of at least three segments separated by a '.'
        # Cannot have a trailing '.'
Enter the fully qualified package name(default: pkg-a.carvel.dev): 
        # A package can have multiple versions associated with it. And users can install one specific version.
Enter the package version to be used(default: v1.0.0):
        # A valuesSchema can be used to show template values that
        # can be configured by users when a Package is installed.
        # These values should be specified in an OpenAPI schema format.
Do you want to specify the values Schema(y/n):
Enter the file location which has the values schema: 
        # Great, we have all the data needed to create the package.yml and packageMetadata.yml. 
        # This is how the package.yml will look like:
        # cat package.yml
        <cat package.yml>
        # This is how the packageMetadata.yml will look like:
        # cat packageMetadata.yml
        <cat packageMetadata.yml>
        # Both the files can be accessed from the following location:
        # Location: 

### Open Questions:
1. Do we have to handle different os for making the links clickable or is there any generic way?
2. How do we show the hyperlinks ?
3. Location where all the packages needs to be stored ?
4. Need version information upfront.
5. How to pass the pkg name and version to the downstream steps?

### Inputs:
1. Why is something recommended. A one liner
2. A line about carvel tool wherever they are consumed first.
3. Implements kctrl pkg init --helm || kctrl pkg init --imgpkg. Basically, something similar to helm create.

### Rough work:

Package Types:
1. imgpkg + upstream config + ytt (recommended)
2. imgpkg + upstream config + ytt
3. imgpkg + helm chart
Enter the package type: 1
        Creating directory <DEFAULT_LOC>/pkg-a/bundle/.imgpkg
        Creating directory <DEFAULT_LOC>/pkg-a/bundle/config/upstream
        Creating directory <DEFAULT_LOC>/pkg-a/bundle/config/upstream

Data sources:(It appears because you have selected 1 in Package Type)
1. GithubRelease
2. Git
3. Image
Enter the data source location from where to fetch: 1

Enter slug for repository(org/repo):
Do you want to use the latest released version(y/n): n
    
Enter the release tag: 

Enter exact release URL(optional): 

Do you want to download only specific release assets(y/n):y
Enter the release assets to be downloaded: 

Do you want to disableAutoChecksumValidation(y/n): y

Do you want to include everything(y/n): n
Enter the paths which needs to be included as part of this package: 

	CMD RUN: 	1. Create vendir.yml file inside bundle directory.
			2. Run vendir sync –chdir bundle
   	OUTPUT:	    Creating vendor.yml file inside bundle directory.
                    Running vendir sync –chdir bundle
	            Also show the output of adobe command

Enter the location of ytt overlay files:
    CMD RUN:     Copy the ytt files to bundle/config/overlays
    
    OUTPUT:      cp 

### Scenario 1: imgpkg bundle(already created) + ytt

roaggarwal:~$ kctrl pkg create pkg-a
        #Lets start off on the package creation for pkg-a
        #First we need a directory to store all configurations
        #Creating directory <DEFAULT_LOC>/pkg-a
        #mkdir -p path
        <mkdir -p path>
        # Done.
        # Next step, is to add the configuration which makes up the package for distribution. Configuration can be fetched from different types of sources. 
Fetch Configuration Types:
1. Imgpkg(recommended)
2. Helm
3. Helm Release
4. Inline
Enter the configuration Type: 1

Do you have the imgpkg bundle details with you(y/n): n
Is the imgpkg bundle already created(y/n): y
        # Now we need to enter the details related to the imgpkg bundle so that it can be fetched and used.
        # First, we need to add the url from where to fetch the image. This url can be: 
        # Unqualified: 
        # Tagged: host.com/username/image:v0.1.0
        # SHA Digest: host.com/username/image@sha256:de02e3f445cfe7c035f2a9939b948c4d043011713389d9437311a62740f20bef
Enter the Image URL:
        # If it is a image hosted on private repository, then we will need the credentials or token. We expect that you would have already created a secret with those credentials or token. For a public image, we don't need the credentials or the secret name.
Enter the secret Name(not needed in case of public image) containing credentails or token: 
# specifies a strategy to choose a tag (optional; v0.24.0+)
        
        # Next step is to define which templating tool to be used to render the package template. 
        # A package template can be rendered by various different tools.
Templating tool types:
1. ytt(recommended)
2. helmTemplate
Enter the templating tool to be used: 1
        # We need to provide the values to ytt. They can be done in three different ways:
        # 1. We can specify the additional files(including data values) to be used via ytt
        # 2. We can enter the values directly i.e. inline
        # 3. They can be picked up from the secret or configmap on the K8s cluster
How do you want to template ytt:
1. ytt files location(recommended)
2. inline
3. valuesFrom configMap or secret
Enter the ytt templating option: 1
Enter the location of ytt files: 
        # Next step is to use kbld to resolve the image references to use digest. kbld will resolve the image and store the digest in a images.yml file.
Enter the path where kbld should store the digest(default: .imgpkg/images.yaml): 
        # A package name must be a fully qualified name. 
        # It must consist of at least three segments separated by a '.'
        # Cannot have a trailing '.'
Enter the fully qualified package name(default: pkg-a.carvel.dev): 
        # A package can have multiple versions associated with it. And users can install one specific version.
Enter the package version to be used(default: v1.0.0):
        # Great, we have all the data needed to create the package.yml and packageMetadata.yml. 
        # This is how the package.yml will look like:
        # cat package.yml
        <cat package.yml>
        # This is how the packageMetadata.yml will look like:
        # cat packageMetadata.yml
        <cat packageMetadata.yml>
        # Bothe the files can be accessed from the following location:
        # Location: