Issuing commands

Apollo will only perform actions on Entities when all constraints, such as maintenance windows and Product dependencies, are satisfied. However, in emergency situations such as a stability incident, you can override the constraints imposed by Apollo and/or the Apollo Plan priority queue to execute a Plan as soon as possible. This is done using commands.

When you issue a command, Apollo will execute the requested action as soon as there is no other active Plan or command on the Entity. If the action must be performed immediately, you can abort an active Plan by creating a suppression window for the Entity and you can abort an active command as described later in this section.

After you execute a command, Apollo will continue evaluating potential Plans for the Entity. It is important to consider other actions that you can use alongside commands, such as recalling a Release and creating a suppression window. Without these actions, the change made using the command could be reverted. For example, if you execute a command to downgrade an Entity without recalling the current Release or creating an Entity-level suppression window, Apollo may issue a plan to upgrade this Entity back if it satisfies all the relevant constraints.

Issue a command

Entity or Environment operators can issue a command by navigating to an Entity's home page and selecting Execute command... from the Actions dropdown menu.

Apollo supports three types of commands: Install, Enforce config, and Enforce config and version. Selecting a command will open a dialog where you can provide a rationale for issuing the command. Once the command is issued, Apollo will attempt to execute it as soon as all necessary conditions are met. You can monitor the progress of the command and see any previously executed commands under the Commands tab of the Entity page.

Only a single command can be pending or executing per Entity. You cannot issue a command for an Entity until the last command you issued has terminated.

Command types

Install

This command is available for Entities showing the Install pending status. It will install the selected Target Version of the Product in the Environment.

Enforce config

This command type will apply the latest configuration overrides to the Entity based on the current running Release.

Enforce config and version

This command type will change the current Release of the Entity to the selected Target version and apply the latest configuration overrides applicable to that version.

Secrets

When issuing a command for an Entity that supports secrets, any pending secret operations will be included in the command and visible in the command spec. This means, for example, that if you issue a command to install a new version of a Product, and there are pending secret operations for that Entity, the command will also include the secret operations.

Command execution

Once a command is issued its status will become pending, meaning that Apollo is waiting for the necessary conditions to be met before executing the command. Generally a command will be in pending status briefly, and will be recommended to the agent at the earliest possible opportunity. However, a command can be blocked from running if Apollo is already doing other work that conflicts with the command. For example, Apollo will never run a command on an Entity that is the target of an active Plan.

If your command is blocked, you can view the reason by hovering over the information icon in its status. If you need your command to run urgently, you can cancel any conflicting Plans by creating suppression windows on the associated Entities.

Command constraints and prioritization

Most work done by Apollo, such as upgrades and configuration changes, is subject to a number of constraints. For instance, Apollo will only perform upgrades on Entities during maintenance windows and it will only upgrade services that are not in an error state. Commands are unique in two respects:

• As long as a command does not conflict with other active Plans, Apollo will always attempt to execute it. Commands are not subject to any of the constraints that apply to Plans. Apollo will execute commands even if the Entity has an active suppression window or if the Entity is not in its maintenance window. Apollo will also execute commands on unhealthy Entities and Entities running recalled Releases.
• Apollo will prioritize commands over Plans. If an Entity has a pending command and a pending upgrade, Apollo will block the upgrade Plan and execute the command. The Plan will run once the command has completed.

Exploring issued and executed commands

From the Entity page you can access the Commands tab to view all commands that were executed for this Entity in the past six months.

For every command, it will display the following:

• The status of the command. Selecting it will provide additional information such as the reason a command failed.
• The type of command that was executed. For an Enforce Config and Version command, the selected target version will also be displayed.
• Who issued the command and when it was issued. You can hover over the question mark to view the rationale that was provided by the issuer of the command.

Cancelling and aborting commands

Any issued or executing commands for an Entity will be displayed at the top of Commands tab.

If you have issued a command and you no longer want it to execute, or it has already started executing but you want to stop it, you can cancel or abort the command. If you cancel a command before it starts executing, the command will never be recommended to the agent. If you abort a command while it is executing, the agent will stop executing the command. Apollo cannot guarantee that an Entity will be in a healthy state after you abort a command. However, Apollo will automatically attempt to start any nodes that are left stopped.

Cancelling a Plan may not be immediate because Apollo cannot terminate a Plan without the agent’s consent. Apollo will communicate to the agent that the Plan should be aborted, but in cases where the agent is down or unresponsive, this could take a long time or never happen.