feat: impl get_files_artifact

core/server/api_container/server/startosis_engine/kurtosis_builtins.go

@@ -10,6 +10,7 @@ import (
  "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/interpretation_time_value_store"
  "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/kurtosis_instruction/add_service"
  "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/kurtosis_instruction/exec"
+ "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/kurtosis_instruction/get_files_artifact"
  "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/kurtosis_instruction/get_service"
  "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/kurtosis_instruction/kurtosis_print"
  "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/kurtosis_instruction/remove_service"
@@ -70,6 +71,7 @@ func KurtosisPlanInstructions(
  add_service.NewAddService(serviceNetwork, runtimeValueStore, packageId, packageContentProvider, packageReplaceOptions, interpretationTimeValueStore, imageDownloadMode),
  add_service.NewAddServices(serviceNetwork, runtimeValueStore, packageId, packageContentProvider, packageReplaceOptions, interpretationTimeValueStore, imageDownloadMode),
  get_service.NewGetService(interpretationTimeValueStore),
+ get_files_artifact.NewGetFilesArtifact(),
  verify.NewVerify(runtimeValueStore),
  exec.NewExec(serviceNetwork, runtimeValueStore),
  kurtosis_print.NewPrint(serviceNetwork, runtimeValueStore),

core/server/api_container/server/startosis_engine/kurtosis_instruction/get_files_artifact/get_files_artifact.go

@@ -0,0 +1,103 @@
+package get_files_artifact
+
+import (
+ "context"
+ "fmt"
+ "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/enclave_plan_persistence"
+ "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/enclave_structure"
+ "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/kurtosis_starlark_framework"
+ "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/kurtosis_starlark_framework/builtin_argument"
+ "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/kurtosis_starlark_framework/kurtosis_plan_instruction"
+ "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/plan_yaml"
+ "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/startosis_errors"
+ "github.com/kurtosis-tech/kurtosis/core/server/api_container/server/startosis_engine/startosis_validator"
+ "go.starlark.net/starlark"
+)
+
+const (
+ GetFilesArtifactBuiltinName = "get_files_artifact"
+ FilesArtifactName = "name"
+
+ descriptionFormatStr = "Fetching files artifact '%v'"
+)
+
+func NewGetFilesArtifact() *kurtosis_plan_instruction.KurtosisPlanInstruction {
+ return &kurtosis_plan_instruction.KurtosisPlanInstruction{
+ KurtosisBaseBuiltin: &kurtosis_starlark_framework.KurtosisBaseBuiltin{
+ Name: GetFilesArtifactBuiltinName,
+ Arguments: []*builtin_argument.BuiltinArgument{
+ {
+ Name: FilesArtifactName,
+ IsOptional: false,
+ ZeroValueProvider: builtin_argument.ZeroValueProvider[starlark.String],
+ Validator: func(value starlark.Value) *startosis_errors.InterpretationError {
+ return builtin_argument.NonEmptyString(value, FilesArtifactName)
+ },
+ },
+ },
+ Deprecation: nil,
+ },
+ Capabilities: func() kurtosis_plan_instruction.KurtosisPlanInstructionCapabilities {
+ return &GetFilesArtifactCapabilities{
+ artifactName: "", // populated at interpretation time
+ description: "", // populated at interpretation time
+ }
+ },
+ DefaultDisplayArguments: map[string]bool{
+ FilesArtifactName: true,
+ },
+ }
+}
+
+type GetFilesArtifactCapabilities struct {
+ artifactName string
+ description string
+}
+
+func (builtin *GetFilesArtifactCapabilities) Interpret(_ string, arguments *builtin_argument.ArgumentValuesSet) (starlark.Value, *startosis_errors.InterpretationError) {
+ artifactNameArgumentValue, err := builtin_argument.ExtractArgumentValue[starlark.String](arguments, FilesArtifactName)
+ if err != nil {
+ return nil, startosis_errors.WrapWithInterpretationError(err, "Unable to extract value for '%s' argument", FilesArtifactName)
+ }
+ artifactName := artifactNameArgumentValue.GoString()
+ builtin.artifactName = artifactName
+ builtin.description = builtin_argument.GetDescriptionOrFallBack(arguments, fmt.Sprintf(descriptionFormatStr, builtin.artifactName))
+
+ // while this instruction simply returns what the input argument was, the returned starlark value can be used to set the files artifact elsewhere
+ return starlark.String(artifactName), nil
+}
+
+func (builtin *GetFilesArtifactCapabilities) Validate(_ *builtin_argument.ArgumentValuesSet, validatorEnvironment *startosis_validator.ValidatorEnvironment) *startosis_errors.ValidationError {
+ // as long as the files artifact exists in the environment, this instruction will evaluate to the files artifact
+ if exists := validatorEnvironment.DoesArtifactNameExist(builtin.artifactName); exists == startosis_validator.ComponentNotFound {
+ return startosis_errors.NewValidationError("Files artifact '%v' required by '%v' instruction doesn't exist", builtin.artifactName, GetFilesArtifactBuiltinName)
+ }
+ return nil
+}
+
+func (builtin *GetFilesArtifactCapabilities) Execute(_ context.Context, _ *builtin_argument.ArgumentValuesSet) (string, error) {
+ // Note this is a no-op
+ return fmt.Sprintf("Fetched files artifact '%v'", builtin.artifactName), nil
+}
+
+func (builtin *GetFilesArtifactCapabilities) TryResolveWith(instructionsAreEqual bool, _ *enclave_plan_persistence.EnclavePlanInstruction, enclaveComponents *enclave_structure.EnclaveComponents) enclave_structure.InstructionResolutionStatus {
+ if instructionsAreEqual && enclaveComponents.HasFilesArtifactBeenUpdated(builtin.artifactName) {
+ return enclave_structure.InstructionIsUpdate
+ } else if instructionsAreEqual {
+ return enclave_structure.InstructionIsEqual
+ }
+ return enclave_structure.InstructionIsUnknown
+}
+
+func (builtin *GetFilesArtifactCapabilities) FillPersistableAttributes(builder *enclave_plan_persistence.EnclavePlanInstructionBuilder) {
+ builder.SetType(GetFilesArtifactBuiltinName).AddFilesArtifact(builtin.artifactName, nil)
+}
+
+func (builtin *GetFilesArtifactCapabilities) UpdatePlan(planYaml *plan_yaml.PlanYaml) error {
+ // get files artifact does not affect the planYaml
+ return nil
+}
+
+func (builtin *GetFilesArtifactCapabilities) Description() string {
+ return builtin.description
+}

docs/docs/api-reference/starlark-reference/plan.md

@@ -125,6 +125,25 @@ service = plan.get_service(
 )
 ```
 
+get_files_artifact
+-----------
+
+The `get_files_artifact` instruction allows you to get a [Files Artifact][files-artifacts-reference] object from a files artifact name. This is
+useful in situations if you don't have access to the instruction that produced the files artifact; perhaps you are in a different function or have imported and run another Kurtosis package.
+
+```python
+# Returns a Files Artifact object 
+artifact = plan.get_files_artifact(
+ # The name of the files artifact to get
+ # MANDATORY
+ name = "config-artifact"
+
+ # A human friendly description for the end user of the package
+ # OPTIONAL (Default: Fetching service 'ARTIFACT_NAME')
+ description = "gets you an artifact"
+)
+```
+
 verify
 ------