Module std — Inmanta 2017.3dev documentation

# Module std

> - License: Apache 2.0
> - Version: 0.14.1
> - Author: Inmanta <code@inmanta.com>
> - This module requires compiler version 2017.2 or higher
> - Upstream project: https://github.com/inmanta/std.git

## Typedefs

typedef `std::hoststring`
  - Base type `string`
  - Type constraint `(self regex re.compile('^[A-Za-z0-9-]+(\\.[A-Za-z0-9-]+)*$'))`

typedef `std::package_state`
  - Base type `string`
  - Type constraint `(((self == 'installed') or (self == 'removed')) or (self == 'latest'))`

typedef `std::service_state`
  - Base type `string`
  - Type constraint `((self == 'running') or (self == 'stopped'))`

typedef `std::uuid`
  - Base type `string`
  - Type constraint `(self regex re.compile('[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}'))`

## Entities

entity `std::AgentConfig`

  Parents: `std::PurgeableResource`

  Control agent settings. Currently these settings are only applied to autostarted agents

  attribute string `agent`='internal'

    If a resource is exported, agent manages the resource.

  attribute bool `autostart`

    When this flag is set to true, the resource will be exported and set the agent map on the orchestrator. When false (or not set), this instance is ignore but can be used to generate agent configuration files.

  attribute string `agentname`

    The name of the agent to which this config applies.

  attribute string `uri`='local:'

    The uri that indicates how the agent should execute. Currently the following uri are supported: * “” An empty string. This is the same as running it locally * local: Manage resource locally * ssh://[user@]hostname[:port] Login using ssh. When user is left out, root is assumed. For port, the system default is used. * host The actual hostname or ip to use. Altough this is not a valid host in uri form it is supported.

  The following implements statements select implementations for this entity:

  > - `std::none`

entity `std::ConfigFile`

  Parents: `std::File`

  A file with often used defaults for configuration files.

  attribute number `mode`=644
  attribute string `owner`='root'
  attribute string `group`='root'

  The following implements statements select implementations for this entity:

  > - `std::reload`

entity `std::DefaultDirectory`

  Parents: `std::Directory`

  A directory that is world readable. It is also writable for its owner root.

  attribute number `mode`=755
  attribute string `owner`='root'
  attribute string `group`='root'

  The following implements statements select implementations for this entity:

  > - `std::reload`

entity `std::Directory`

  Parents: `std::Reload`, `std::PurgeableResource`

  A directory on the filesystem

  attribute string `owner`
  attribute bool `purge_on_delete`=False
  attribute number `mode`
  attribute string `group`
  attribute string `path`
  relation std::Host `host` [1]

    other end: `std::Host.directories [0:*]`

  The following implements statements select implementations for this entity:

  > - `std::reload`

entity `std::Entity`

  The entity all other entities inherit from.

  relation std::Entity `requires` [0:*]

    other end: `std::Entity.provides [0:*]`

  relation std::Entity `provides` [0:*]

    other end: `std::Entity.requires [0:*]`

  The following implementations are defined for this entity:

  > - `std::none`

entity `std::File`

  Parents: `std::Reload`, `std::PurgeableResource`

  This represents a file on the filesystem

  attribute string `owner`

    The owner of the file

  attribute bool `send_event`
  attribute bool `purge_on_delete`=False
  attribute number `mode`

    The permissions of the file

  attribute string `content`

    The file contents

  attribute string `group`

    The group of the file

  attribute string `path`

    The path of the file

  relation std::Host `host` [1]

    other end: `std::Host.files [0:*]`

  The following implements statements select implementations for this entity:

  > - `std::reload`

entity `std::Host`

  Parents: `std::ManagedDevice`

  A host models a server of computer in the managed infrastructure

  relation std::Directory `directories` [0:*]

    other end: `std::Directory.host [1]`

  relation std::HostConfig `host_config` [1]

    other end: `std::HostConfig.host [1]`

  relation std::Symlink `symlinks` [0:*]

    other end: `std::Symlink.host [1]`

  relation net::Interface `ifaces` [0:*]

    other end: `net::Interface.host [1]`

  relation std::Package `packages` [0:*]

    other end: `std::Package.host [1]`

  relation std::File `files` [0:*]

    other end: `std::File.host [1]`

  relation std::OS `os` [1]

    Each host has an OS defined. This values is mostly used to select implementation in the where clause of an implement statement. The `familyof()` plugin can be used for this.

  relation std::HostGroup `host_groups` [0:*]

    other end: `std::HostGroup.hosts [0:*]`

  relation apt::Repository `repository` [0:*]

    other end: `apt::Repository.host [1]`

  relation std::Service `services` [0:*]

    other end: `std::Service.host [1]`

  The following implementations are defined for this entity:

  > - `std::hostDefaults`

  The following implements statements select implementations for this entity:

  > - `std::hostDefaults`

entity `std::HostConfig`

  Parents: `std::Entity`

  This represents generic configuration for a host. This entity is used by other modules to include their host specific configuration. This should be instantiated in the implementation of std::Host or subclasses. This host specific configuration cannot be included by just implementing std::Host because possibly subclasses of std::Host are instantiated and implementations are not inherited.

  relation std::Host `host` [1]

    other end: `std::Host.host_config [1]`

  The following implementations are defined for this entity:

  > - `redhat::scl::epel7`
  > - `redhat::network::config`
  > - `ip::agentConfig`
  > - `redhat::epel::epel7`

  The following implements statements select implementations for this entity:

  > - `redhat::scl::epel7` constraint `(std::familyof(host.os,'rhel') and (host.os.version >= 7))`
  > - `redhat::network::config` constraint `std::familyof(host.os,'redhat')`
  > - `std::none`
  > - `ip::agentConfig` constraint `(host.ip is defined is defined and host.remote_agent)`
  > - `redhat::epel::epel7` constraint `(std::familyof(host.os,'rhel') and (host.os.version >= 7))`

entity `std::HostGroup`

  Parents: `std::Entity`

  This entity represents a group of hosts. For example a cluster of machines.

  attribute string `name`
  relation std::Host `hosts` [0:*]

    other end: `std::Host.host_groups [0:*]`

  The following implements statements select implementations for this entity:

  > - `std::none`

entity `std::ManagedDevice`

  Parents: `std::Entity`

  This interface represents all devices that can be managed

  attribute std::hoststring `name`

entity `std::ManagedResource`

  Parents: `std::Resource`

  A base class for a resource that can be ignored/unmanaged by Inmanta.

  attribute bool `managed`=True

    This determines whether this resource is managed by Inmanta or not.

entity `std::OS`

  Parents: `std::Entity`

  Defines an operating system

  attribute string `name`
  attribute number `version`=0
  relation std::OS `member` [0:*]

    other end: `std::OS.family [0:1]`

  relation std::OS `family` [0:1]

    other end: `std::OS.member [0:*]`

  The following implements statements select implementations for this entity:

  > - `std::none`

entity `std::Package`

  Parents: `std::Reload`

  A software package installed on a managed device.

  attribute string `name`

    The name of the package to manage

  attribute std::package_state `state`

    The state of the package. Valid values are ‘installed’, ‘removed’ or ‘latest’. latest will upgrade the package when an update is available.

  relation std::Host `host` [1]

    other end: `std::Host.packages [0:*]`

  The following implements statements select implementations for this entity:

  > - `std::reload`

entity `std::PurgeableResource`

  Parents: `std::Resource`

  A base class for a resource that can be purged and can be purged by Inmanta whenever the resource is no longer managed.

  attribute bool `purge_on_delete`=True

    Purge the resource when it is deleted from the configuration model. When this attribute is true, the server will include a resource with purged=true when this resource is no longer included in the configuration model.

  attribute bool `purged`=False

    Set whether this resource should exist or not.

entity `std::Reload`

  Parents: `std::Resource`

  An entity to make the (old) reload mechanism compatible with the event mechanism

  attribute bool `reload`=False

    If a service requires this file, reload or restart the service when this file changes.

  attribute bool `send_event`

  The following implementations are defined for this entity:

  > - `std::reload`

entity `std::Resource`

  Parents: `std::Entity`

  A base entity for resources that can be exported. This type add specific attributes that are common for most handlers. It is not required to inherit from this entity at the moment but highly recommended for documentation purposes.

  attribute bool `send_event`=False

    This controls wether a resource should send its deploy state to the resources in its provides.

entity `std::Service`

  Parents: `std::Reload`

  Manage a service on a host.

  attribute string `name`

    The name of the service to manage

  attribute bool `onboot`

    Should the service start on boot.

  attribute std::service_state `state`

    The desired state of the service. Valid values are ‘running’ or ‘stopped’

  relation std::Host `host` [1]

    other end: `std::Host.services [0:*]`

  The following implements statements select implementations for this entity:

  > - `std::reload`

entity `std::State`

  Parents: `std::Entity`

  Baseclass for entities that contain state

  attribute bool `allow_restore`=True

    Allow a restore of the state containted in this entity

  attribute bool `allow_snapshot`=True

    Allow a snapshot of the state contained in this entity

  attribute string `state_id`=''

    The id to identify the state. If left empty, the resource id is used. (This can be used for cross environment/model restores)

entity `std::Symlink`

  Parents: `std::Reload`, `std::PurgeableResource`

  A symbolic link on the filesystem

  attribute string `source`
  attribute bool `send_event`
  attribute bool `purge_on_delete`=False
  attribute string `target`
  relation std::Host `host` [1]

    other end: `std::Host.symlinks [0:*]`

  The following implements statements select implementations for this entity:

  > - `std::reload`

## Implementations

implementation `std::hostDefaults`

implementation `std::none`

  An empty implementation that can be used as a safe default.

implementation `std::reload`

## Plugins

`std.` `all`(item_list: list, expression: expression) → bool

  This method returns false when at least one item does not evaluate expression to true, otherwise it returns true

  Parameters: | expression – An expression that accepts one argument and returns true or false

`std.` `any`(item_list: list, expression: expression) → bool

  This method returns true when at least on item evaluates expression to true, otherwise it returns false

  Parameters: | expression – An expression that accepts one arguments and returns true or false

`std.` `assert`(expression: bool, message: string=)

  Raise assertion error is expression is false

`std.` `at`(objects: list, index: number) → any

  Get the item at index

`std.` `attr`(obj: any, attr: string) → any

`std.` `capitalize`(string: string) → string

  Capitalize the given string

`std.` `count`(item_list: list) → number

  Returns the number of elements in this list

`std.` `delay`(x: any) → any

  Delay evaluation

`std.` `each`(item_list: list, expression: expression) → list

  Iterate over this list executing the expression for each item.

  Parameters: | expression – An expression that accepts one arguments and is evaluated for each item. The returns value of the expression is placed in a new list

`std.` `environment`() → string

  Return the environment id

`std.` `environment_name`() → string

  Return the name of the environment (as defined on the server)

`std.` `environment_server`() → string

  Return the address of the management server

`std.` `equals`(arg1: any, arg2: any, desc: string=None)

  Compare arg1 and arg2

`std.` `familyof`(member: std::OS, family: string) → bool

  Determine if member is a member of the given operating system family

`std.` `file`(path: string) → string

  Return the textual contents of the given file

`std.` `first_of`(value: list, type_name: string) → any

  Return the first in the list that has the given type

`std.` `flatten`(item_list: list) → list

  Flatten this list

`std.` `generate_password`(pw_id: string, length: number=20) → string

  Generate a new random password and store it in the data directory of the project. On next invocations the stored password will be used.

  Parameters: | pw_id – The id of the password to identify it. length – The length of the password, default length is 20

`std.` `get`(path: string) → any

  This function return the variable with given string path

`std.` `get_env`(name: string, default_value: string=None) → string

`std.` `get_env_int`(name: string, default_value: number=None) → number

`std.` `getfact`(resource: any, fact_name: string, default_value: any=None) → any

  Retrieve a fact of the given resource

`std.` `inlineif`(conditional: bool, a: any, b: any) → any

  An inline if

`std.` `is_instance`(obj: any, cls: string) → bool

`std.` `is_set`(obj: any, attribute: string) → bool

`std.` `isset`(value: any) → bool

  Returns true if a value has been set

`std.` `item`(objects: list, index: number) → list

  Return a list that selects the item at index from each of the sublists

`std.` `key_sort`(items: list, key: any) → list

  Sort an array of object on key

`std.` `objid`(value: any) → string

`std.` `order_by`(item_list: list, expression: expression=None, comparator: expression=None) → list

  This operation orders a list using the object returned by expression and optionally using the comparator function to determine the order.

  Parameters: | expression – The expression that selects the attributes of the items in the source list that are used to determine the order of the returned list. comparator – An optional expression that compares two items.

`std.` `password`(pw_id: string) → string

  Retrieve the given password from a password file. It raises an exception when a password is not found

  Parameters: | pw_id – The id of the password to identify it.

`std.` `print`(message: any)

  Print the given message to stdout

`std.` `replace`(string: string, old: string, new: string) → string

`std.` `select`(objects: list, attr: string) → list

  Return a list with the select attributes

`std.` `select_attr`(item_list: list, attr: string) → list

  This query method projects the list onto a new list by transforming the list as defined in the expression.

`std.` `select_many`(item_list: list, expression: expression, selector_expression: expression=None) → list

  This query method is similar to the select query but it merges the results into one list.

  Parameters: | expresion – An expression that returns the item that is to be included in the resulting list. If that item is a list itself it is merged into the result list. The first argument of the expression is the item in the source sequence. selector_expression – This optional arguments allows to provide an expression that projects the result of the first expression. This selector expression is equivalent to what the select method expects. If the returned item of expression is not a list this expression is not applied.

`std.` `sequence`(i: number, start: number=0, offset: number=0) → list

  Return a sequence of i numbers, starting from zero or start if supplied.

`std.` `server_ca`()

`std.` `server_password`() → string

`std.` `server_port`() → number

`std.` `server_username`() → string

`std.` `source`(path: string) → string

  Return the textual contents of the given file

`std.` `split`(string_list: string, delim: string) → list

  Split the given string into a list

  Parameters: | string_list – The list to split into parts delim – The delimeter to split the text by

`std.` `template`(path: string)

  Execute the template in path in the current context. This function will generate a new statement that has dependencies on the used variables.

`std.` `timestamp`(dummy: any=None) → number

  Return an integer with the current unix timestamp

  Parameters: | any – A dummy argument to be able to use this function as a filter

`std.` `type`(obj: any) → any

`std.` `unique`(item_list: list) → bool

  Returns true if all items in this sequence are unique

`std.` `unique_file`(prefix: string, seed: string, suffix: string, length: number=20) → string

`std.` `where`(item_list: list, expression: expression) → list

  This query method selects the items in the list that evaluate the expression to true.

  Parameters: | expression – An expression that returns true or false to determine if an item from the list is included. The first argument of the expression is the item that is to be evaluated. The second optional argument is the index of the item in the list.

`std.` `where_compare`(item_list: list, expr_list: list) → list

  This query selects items in a list but uses the tupples in expr_list to select the items.

  Parameters: | expr_list – A list of tupples where the first item is the attr name and the second item in the tupple is the value

## Resources

class `std.resources.` `AgentConfig`

  > A resource that can modify the agentmap for autostarted agents

  - Resource for entity `std::AgentConfig`
  - Id attribute `agentname`
  - Agent name `agent`
  - Handlers `std.resources.AgentConfigHandler`

class `std.resources.` `Directory`

  > A directory on a filesystem

  - Resource for entity `std::Directory`
  - Id attribute `path`
  - Agent name `host.name`
  - Handlers `std.resources.DirectoryHandler`

class `std.resources.` `File`

  > A file on a filesystem

  - Resource for entity `std::File`
  - Id attribute `path`
  - Agent name `host.name`
  - Handlers `std.resources.PosixFileProvider`

class `std.resources.` `Package`

  > A software package installed on an operating system.

  - Resource for entity `std::Package`
  - Id attribute `name`
  - Agent name `host.name`
  - Handlers `apt.AptPackage`, `std.resources.YumPackage`

class `std.resources.` `Service`

  > This class represents a service on a system.

  - Resource for entity `std::Service`
  - Id attribute `name`
  - Agent name `host.name`
  - Handlers `std.resources.ServiceService`, `ubuntu.UbuntuService`, `std.resources.SystemdService`

class `std.resources.` `Symlink`

  > A symbolic link on the filesystem

  - Resource for entity `std::Symlink`
  - Id attribute `target`
  - Agent name `host.name`
  - Handlers `std.resources.SymlinkProvider`

## Handlers

class `std.resources.` `PosixFileProvider`

  > This handler can deploy files on a unix system

  - Handler name `posix_file`
  - Handler for entity `std::File`

class `std.resources.` `DirectoryHandler`

  > A handler for creating directories

  > TODO: add recursive operations

  - Handler name `posix_directory`
  - Handler for entity `std::Directory`

class `std.resources.` `ServiceService`

  > A handler for services on systems that use service

  - Handler name `redhat_service`
  - Handler for entity `std::Service`

class `std.resources.` `SystemdService`

  > A handler for services on systems that use systemd

  - Handler name `systemd`
  - Handler for entity `std::Service`

class `std.resources.` `AgentConfigHandler`
  - Handler name `agentrest`
  - Handler for entity `std::AgentConfig`

class `std.resources.` `YumPackage`

  > A Package handler that uses yum

  - Handler name `yum`
  - Handler for entity `std::Package`

class `std.resources.` `SymlinkProvider`

  > This handler can deploy symlinks on unix systems

  - Handler name `posix_symlink`
  - Handler for entity `std::Symlink`