property

Usage

fugue [global options] property [options] (<FID> | <alias>) <key> [--set <value>]

Arguments

<FID> | <alias>

FID or alias of the target process

Available keys:

  • alias: The process’s alias
  • lock: The process’s lock state, defaults to OFF
  • enforcement: The process’s enforcement state

Options

Global options are detailed here.

--set <value>
Set the <key> to the provided <value>
--json
Emit output as JSON. The JSON flag displays command output in JSON format, which is useful for automation.
--help
Show help text. The help flag is available throughout the CLI in both an application-level and command-level context. It enables a user to view help text for any command within the Fugue CLI.

Definition

The property command gets or sets a property of a Fugue process.

  • alias returns a process’s alias or changes it.
  • lock turns access to a process ON or OFF. Locking is turned OFF by default.
  • enforcement returns a process’s enforcement state. Enforcement is turned ON by default.

Examples

Returning the alias of a process

If you know the FID of a process and you want to find out what its alias is, you can use property with alias:

$ fugue property ce757615-5b75-49eb-a5a5-0733eed8b0d3 alias

The CLI returns the alias:

"staging"

To return the alias as JSON, use the --json flag:

$ fugue property --json ce757615-5b75-49eb-a5a5-0733eed8b0d3 alias

The CLI returns the alias as JSON:

{
    "fid": "ce757615-5b75-49eb-a5a5-0733eed8b0d3",
    "alias": "staging"
}

Changing the alias of a process

If you want to change the alias of a running process, you can use property with alias. This command allows you to update the alias with no impact to your infrastructure.

Say you have a process with the alias staging, but you need to change it to a new alias, develop.

To change an alias by providing the process’s FID, follow this format: fugue property <FID> alias --set <value>

$ fugue property ce757615-5b75-49eb-a5a5-0733eed8b0d3 alias --set develop

The CLI returns the new alias:

"develop"

As with other commands, you can also substitute an alias for a FID when invoking this command. For example, for a process with the alias myProcess, this command would change the alias to develop.

$ fugue property myProcess alias --set develop

To return the output as JSON, use the --json flag and provide either the FID or the old alias in this format: fugue property --json <FID | alias> alias --set <value>

$ fugue property --json myProcess --set develop

The CLI returns the new alias as JSON:

{
    "fid": "ce757615-5b75-49eb-a5a5-0733eed8b0d3",
    "alias": "develop"
}

Alias format

An alias must meet the following criteria:

  • It must be unique. If an alias already exists, the Fugue CLI returns an error.
  • It must not match the format of a UUID (i.e., 00000000-0000-0000-0000-000000000000).

Returning a process’s enforcement state

If you want to find out whether enforcement is enabled for a process, you can use property with the enforcement key and the process’s FID or alias:

fugue property 174caf89-6ec1-40f9-99f7-abfd032daa45 enforcement

The CLI returns the process’s state of enforcement as either "ON" or "OFF":

"ON"

To return the enforcement state as JSON, use the --json flag:

fugue property --json 174caf89-6ec1-40f9-99f7-abfd032daa45 enforcement

The CLI will return the output as JSON:

{
    "enforcement_level": "ON",
    "fid": "174caf89-6ec1-40f9-99f7-abfd032daa45"
}

Turning enforcement on or off for a process

Fugue enforces your infrastructure by comparing its state to the declarations in your Ludwig code and correcting untracked differences, such as drift. By default, process enforcement is enabled. Read more about enforcement here.

To turn enforcement off, use the following command, substituting your FID or alias for the FID below:

fugue property 174caf89-6ec1-40f9-99f7-abfd032daa45 enforcement --set off

The CLI will return the following confirmation:

"OFF"

To turn enforcement back on, use the following command, again substituting your own FID or alias:

fugue property 174caf89-6ec1-40f9-99f7-abfd032daa45 enforcement --set on

The CLI will return the following confirmation:

"ON"

Warning

Attempting an update while enforcement is turned off can result in unexpected behavior, particularly if enforcement was disabled to allow infrastructure modification outside of Fugue. We recommend turning enforcement back on before executing an update.

In addition, if an update fails during execution for a process where enforcement is set to OFF, the process will never reach the desired state in the revised composition (i.e. it won’t retry the update).

Locking a process

To lock a process you can use property with the --set flag.

In this example, the CLI displays the following Flags:

$ fugue status

Fugue Status Report for user/xxxxxxxxxx - Mon Nov 13 2017 4:07pm

State    Updated    Created    Account     FID/Alias      Flags    Last Message
-------  ---------  ---------  ---------   -------------  -------  --------------
Running  12:29pm    11:37am    fugue       mycomposition  --       SUCCEEDED
Running  11:53am    11:53am    fugue       myprocess      -e       SUCCEEDED
Running  11:38am    11:38am    fugue       vpc-only       -e       SUCCEEDED

The first process mycomposition has no lock and enforcement is DISABLED, resulting in no flags, e.g. --. The myprocess and vpc-only processes are both using the default enabled enforcement, e.g. e.

To lock a process, issue the following command, specifying the FID or alias, in this example myprocess:

$ fugue property myprocess lock --set on
"ON"

You will immediately receive the confirmation ON and can verify the change in lock status using the fugue status command:

$ fugue status

Fugue Status Report for user/xxxxxxxxxx - Mon Nov 13 2017 4:07pm

State    Updated    Created    Account     FID/Alias      Flags    Last Message
-------  ---------  ---------  ---------   -------------  -------  --------------
Running  12:29pm    11:37am    fugue       mycomposition  --       SUCCEEDED
Running  11:53am    11:53am    fugue       myprocess      le       SUCCEEDED
Running  11:38am    11:38am    fugue       vpc-only       -e       SUCCEEDED

To unlock this process simply issue the same command and with the --set flag, in this example:

$ fugue property myprocess lock --set off

fugue suspend vs. fugue property enforcement

What’s the difference between using fugue suspend and fugue property enforcement to pause enforcement? In both cases, Fugue stops actively managing a process’s resources.

The big difference is that if enforcement is turned off with fugue property enforcement, jobs and notifications continue to be issued. This means that the Conductor will still calculate enforcement changes, though it will not apply them. If drift occurs, the Conductor’s internal components create a plan to correct it and send that plan to the Conductor event notification service, so if you are subscribed to the fugue-notifications-drift SNS topic, you’ll be alerted to the drift.

In contrast, when enforcement is suspended using fugue suspend, the Conductor does not calculate enforcement changes, and no drift notifications are sent.

Another difference between the commands is if a process has been suspended with fugue suspend, you may execute the fugue update command and the update will take effect as soon as the process is resumed with fugue resume.

Warning

Attempting an update while enforcement is turned off can result in unexpected behavior, particularly if enforcement was disabled to allow infrastructure modification outside of Fugue. We recommend turning enforcement back on before executing an update.

In addition, if an update fails during execution for a process where enforcement is set to OFF, the process will never reach the desired state in the revised composition (i.e. it won’t retry the update).