docs: what is the expected jsonnet output?

[ghostsquad]

Summary

The documentation for how to use jsonnet with ArgoCD is a bit sparse. The main question I have is whether or not ArgoCD uses the direct output from the jsonnet render? or if it still expects files to be generated, and uses those?

Motivation

For my use case I have a script like this:

$JSONNET \
    ${jsonnet_tla_strs[@]/#/--tla-str } \
    ${jsonnet_tla_codes[@]/#/--tla-code } \
    -J "${repo_dir}/vendor" \
    -m "${repo_dir}" "${config_environments_dir}/${workspace}.jsonnet" \
    > "${jsonnet_output_files_tmp_file}"

files=()
while IFS='' read -r line; do files+=("$line"); done < "${jsonnet_output_files_tmp_file}"

for i in "${files[@]}"
do
    :

    # Create YAML files cause they are easier to read
    # but otherwise won't be used in some cases
    $YQ r -P "${i}" | cat "${deployment_dir}/do-not-edit-header.txt" - > "${i}.yml"

    rm -f "${i}"
done

I use -m jsonnet to "write" the object keys (like how kube-prometheus) works as files, i.e.

dist/deployment

then transform those created files into YAML files, i.e.

dist/deployment.yaml

This is a fairly simple bash script (called from a Makefile).

I'd like to maintain the same "method" of generating the manifests both in and out of my CI/CD pipeline.

Proposal

More documentation, and also see proposal in #3688

[xvzf]

I'm currently working on #3688 (at least for the additional lib search paths). What I found so far regarding the template generation:

Everything is handled by a VM instance of https://github.com/google/go-jsonnet. Argo walks a directory, scans for files with the matching *.jsonnet and evaluates it. It supports objects and arrays and passes the to the k8s processor. Have a look here (perm link of master 22.06.2020) https://github.com/argoproj/argo-cd/blob/fc2e3f82a2f23669a83fb5c9ae36b4e35a7e9aa6/reposerver/repository/repository.go#L548

[xvzf]

@ghostsquad feel free to review the documentation changes here: https://github.com/argoproj/argo-cd/pull/3825/files#diff-a69080dc0016c2e4278bd9e80701fa68

IMO this addresses this issue as well

[ghostsquad]

@xvzf I don't think that the PR solves the issue, as it does not explain what's valid from the jsonnet output side.

no nesting

{
kind: "Deployment"
...
}

an array of objects

[
{
kind: "Deployment"
...
},
]

an object of objects (tanka style)

{
deployment: {
kind: "Deployment"
...
},
}

At the end of the day, what's the jsonnet commandline equivalent that should be used? E.g.

This expects an array of objects (which is converted to yaml doc stream)

jsonnet --yaml-stream

Additionally, is ARGO CD evaluating each and every jsonnet file and passing the TLA's and ExtVar params to each one? what happens when you have multiple jsonnet files (#3947)

[alexmt]

Hello @ghostsquad,

I've just checked - right now Argo CD expects a single one or more JSON encoded Kubernetes resource (so option two - an array of objects).

I think this is a bug or at least need ehnancement. All other tools might produce anything compatible with kubectl apply (JSON/YAML and might have one or more resources). I'm sending PR with the an improvement soon.