[Documentation] Information about Trial meta injection in template

[andreyvelich]

/kind feature

After this PR: #1259, user can use Trial metadata in Trial parameters.
We should explain how to use substitution in template for metadata parameters.

[issue-label-bot]

Issue-Label Bot is automatically applying the labels:

Label	Probability
area/front-end	0.74

Please mark this comment with 👍 or 👎 to give our bot feedback!
Links: app homepage, dashboard and code for this bot.

[terrykong]

Hi @andreyvelich . After the merge of the new trial template, is there still a mechanism to get the trial name? For reference, the gotemplate way of referencing it was https://github.com/kubeflow/katib/pull/1202/files#diff-82dc48b655cb8b5eff0c7fe15d75607bL47, but all v1beta1 examples don't have that field anymore. Is there a way of referencing that variable?

The use case here is when running a trial I create intermediate files in a directory that has the same name as the trial that are useful to analyze after the full experiment is run.

[andreyvelich]

Hi @terrykong, yes it is possible.

@sperlingxx implemented it in #1259.

You can get data from metadata.name, metadata.namespace, Kind, APIVersion , metadata.labels[x], metadata.annotations[x] from Trial running Job and use it for substitution.

We need to document it.
I will submit PR with example, how you can use these values.

[terrykong]

Cool, looking forward to the documentation. Thanks for pointing out the relevant PR.

So I was a little impatient and went ahead and tried to do it myself. Following https://github.com/kubeflow/katib/blob/master/pkg/controller.v1beta1/experiment/manifest/generator_test.go I got it to work, but I'm curious if this design was intended. To make things work I need to specify all the metadata variables I want in the trialParameters, e.g.,

trialTemplate:
    trialParameters:
      - name: dummyparam
        description: a dummy parameter
        reference: -dp
      - name: foobar
        description: a dummy parameter
        reference: -foobar
      - name: trialName
        description: the name of the trial
        reference: ${trialSpec.Name}
      - name: trialNamespace
        description: namespace of current trial
        reference: ${trialSpec.Namespace}
      - name: jobKind
        description: job kind of current trial
        reference: ${trialSpec.Kind}
      - name: jobAPIVersion
        description: job API Version of current trial
        reference: ${trialSpec.APIVersion}

And I noticed that this works if in my container's command I specify the metadata variables like so:

                  echo trialParameters.trialName="${trialParameters.trialName}";
                  echo trialParameters.trialNamespace="${trialParameters.trialNamespace}";
                  echo trialParameters.jobKind="${trialParameters.jobKind}";
                  echo trialParameters.jobAPIVersion="${trialParameters.jobAPIVersion}";

But what I'm curious about is why directly referencing the variable from the trialSpec like this, isn't supported:

                  echo trialSpec.Name=${trialSpec.Name};
                  echo trialSpec.Namespace=${trialSpec.Namespace};
                  echo trialSpec.Kind=${trialSpec.Kind};
                  echo trialSpec.APIVersion=${trialSpec.APIVersion};

[terrykong]

Actually apologies, there was already quite a bit of discussion about this in #1259. I jumped the gun early before reading. I understand the reasoning now. It's not too much of an issue to lay out all the metadata params a user plans on using, I was merely curious~

[andreyvelich]

/priority p1
/area release

[andreyvelich]

This has been done in: kubeflow/website#2332.