Getting started

For installation of the Ankaios SDK, see the Installation section.

Once the SDK is installed, you can start using it by importing the module and creating an Ankaios object. The prefered method to use the Ankaios class is by using the context manager. This way, the connection to the control interface is automatically closed when the context is exited.

from ankaios_sdk import Ankaios

with Ankaios() as ankaios:
    # Your code here

The initialization of the Ankaios object will automatically connect to the fifo pipes of the control interface. Once this is done, the communication with the Ankaios cluster can be started.

Apply a manifest

Considering we have the following manifest file with a workload called nginx:

my_manifest.yaml
apiVersion: v0.1
workloads:
    nginx:
        runtime: podman
        restartPolicy: NEVER
        agent: agent_A
        runtimeConfig: |
            image: image/nginx

The manifest can now be applied using the following code:

from ankaios_sdk import Ankaios, Manifest

# Create an Ankaios object
with Ankaios() as ankaios:

    # Load the manifest from the file
    manifest = Manifest.from_file('my_manifest.yaml')

    # Apply the manifest and get the result
    ret = ankaios.apply_manifest(manifest)

    # Get the workload instance name
    wl_instance_name = ret.added_workloads[0]

    # Print the instance name
    print(wl_instance_name)

    # Get the workload state based on the instance name
    execution_state = ankaios.get_execution_state_for_instance_name(wl_instance_name)

    # Output the state
    print(execution_state.state)
    print(execution_state.substate)
    print(execution_state.additional_info)

If the operation is successful, the result will be an UpdateStateSuccess object that contains the added and deleted workload instance names. The workload instance name contains the name of the workload, the agent it is running on and a unique identifier. Using it, we can request the current execution state of the workload. The state has 3 elements: the primary state, the substate and additional information (See Workload States).

Get the complete state

The complete state of the Ankaios system can be retrieved using the get_state method of the Ankaios class:

from ankaios_sdk import Ankaios

# Create an Ankaios object
with Ankaios() as ankaios:

    # Get the complete state
    complete_state = ankaios.get_state()

    # Output the state
    print(complete_state)

The complete state contains information regarding the workloads running in the Ankaios cluster, configurations and agents. The state can be filtered using filter masks (See get_state).

Update a workload

Considering we have the above workload running, we can now modify it. For this example we will update the restartPolicy. To be able to pinpoint the exact workload we want to modify, we must know only it’s name.

from ankaios_sdk import Ankaios

# Create an Ankaios object
with Ankaios() as ankaios:

    # Get the workload based on the name
    workload = ankaios.get_workload("nginx")

    # Update the restart policy
    ret = workload.update_restart_policy("ALWAYS")

    # Unpack the result
    added_workloads = ret.added_workloads
    deleted_workloads = ret.deleted_workloads

Depending on the updated parameter, the workload can be restarted or not. If this is the case, the deleted_workloads will contain the old instance name and the added_workloads will contain the new one.

Delete a workload

There are multiple methods to delete a workload: we can either use the same manifest that we used to start it and call delete_manifest or we can delete the workload based on its name. In this example, we will delete the workload using the manifest. Considering the same manifest as before (my_manifest.yaml):

from ankaios_sdk import Ankaios, Manifest

# Create an Ankaios object
with Ankaios() as ankaios:

    # Load the manifest from the file
    manifest = Manifest.from_file('my_manifest.yaml')

    # Delete the manifest (this will delete the workload contained in the manifest)
    ret = ankaios.delete_manifest(manifest)

    # Get the workload instance name
    wl_instance_name = ret.deleted_workloads[0]

    # Print the instance name of the deleted workload
    print(wl_instance_name)

Notes