class DomainObject(Linkable):
domainType: fields.Field = fields.String(required=True)
# Generic things to ease development. Should be changed for more concrete schemas.
id = fields.String()
title = fields.String()
members = fields.Nested(ObjectMemberDict())
extensions = fields.Dict()
class ObjectMemberBase(Linkable):
id = fields.String(required=True)
disabledReason = fields.String(
description=
('Provides the reason (or the literal "disabled") why an object property or '
'collection is un-modifiable, or, in the case of an action, unusable (and '
'hence no links to mutate that member\'s state, or invoke the action, are '
'provided).'),
allow_none=True,
)
invalidReason = fields.String(
description=
('Provides the reason (or the literal "invalid") why a proposed value for a '
'property, collection or action argument is invalid. Appears within an '
'argument representation 2.9 returned as a response.'),
example="invalid",
allow_none=True,
)
x_ro_invalidReason = fields.String(
dump_to="x-ro-invalidReason",
description=
("Provides the reason why a SET OF proposed values for properties or arguments "
"is invalid."),
allow_none=True,
)
class CreateFolder(BaseSchema):
"""Creating a folder
Every folder needs a parent folder to reside in. The uppermost folder is called the "root"
Folder and has the fixed identifier "root".
Parameters:
* `name` is the actual folder-name on disk.
* `title` is meant for humans to read.
* `parent` is the identifier for the parent-folder. This identifier stays the same,
even if the parent folder is being moved.
* `attributes` can hold special configuration parameters which control various aspects of
the monitoring system. Most of these attributes will be inherited by hosts within that
folder. For more information please have a look at the
[Host Administration chapter of the handbook](https://checkmk.com/cms_wato_hosts.html#Introduction).
"""
name = fields.String(description="The name of the folder.", required=True, example="production")
title = fields.String(
required=True,
example="Production Hosts",
)
parent = FolderField(
description=("The folder-id of the folder under which this folder shall be created. May be "
"'root' for the root-folder."),
pattern="[a-fA-F0-9]{32}|root",
example="root",
required=True,
)
attributes = AttributesField(
description=("Specific attributes to apply for all hosts in this folder "
"(among other things)."),
missing=dict,
example={},
)
class InputHostTagGroup(BaseSchema):
ident = HostTagGroupId(
example="group_id",
description="An id for the host tag group",
attribute="id",
)
title = fields.String(
required=True,
example="Kubernetes",
description="A title for the host tag",
)
topic = fields.String(
required=True,
example="Data Sources",
description="Different tags can be grouped in a topic",
)
help = fields.String(
required=False,
example="Kubernetes Pods",
description="A help description for the tag group",
missing="",
)
tags = Tags(
fields.Nested(HostTag),
required=True,
example=[{
"ident": "pod",
"title": "Pod"
}],
description="A list of host tags belonging to the host tag group",
)
class UpdateHostTagGroup(BaseSchema):
title = fields.String(
required=False,
example="Kubernetes",
description="A title for the host tag",
)
topic = fields.String(
required=False,
example="Data Sources",
description="Different tags can be grouped in a topic",
)
help = fields.String(
required=False,
example="Kubernetes Pods",
description="A help description for the tag group",
)
tags = Tags(
fields.Nested(HostTag),
required=False,
example=[{
"ident": "pod",
"title": "Pod"
}],
description="A list of host tags belonging to the host tag group",
)
repair = fields.Boolean(
required=False,
missing=False,
example=False,
description=
"The host tag group can be in use by other hosts. Setting repair to True gives permission to automatically update the tag from the affected hosts."
)
class ConcreteTimePeriod(BaseSchema):
alias = fields.String(description="The alias of the time period",
example="alias")
active_time_ranges = fields.List(
fields.Nested(ConcreteTimeRangeActive),
description="The days for which time ranges were specified",
example={
'day': 'all',
'time_ranges': [{
'start': '12:00',
'end': '14:00'
}]
},
)
exceptions = fields.List(
fields.Nested(ConcreteTimePeriodException),
description="Specific day exclusions with their list of time ranges",
example=[{
'date': '2020-01-01',
'time_ranges': [{
'start': '14:00',
'end': '18:00'
}]
}],
)
exclude = fields.List( # type: ignore[assignment]
fields.String(description="Name of excluding time period",
example="holidays"),
description=
"The collection of time period aliases whose periods are excluded",
)
class FolderSchema(Linkable):
domainType = fields.Constant(
"folder_config",
required=True,
)
id = fields.String()
title = fields.String()
members = fields.Nested(FolderMembers())
class ObjectProperty(Linkable):
id = fields.String(
description=
"The unique name of this property, local to this domain type.")
# FIXME: This is the only use-case right now. Needs to be expanded when this is used more.
value = fields.List(
fields.String(),
description="The value of the property. In this case a list.",
)
extensions = fields.Dict(
description="Additional attributes alongside the property.", )
class InstalledVersions(BaseSchema):
site = fields.String(
description="The site where this API call was made on.",
example="production")
group = fields.String(
description="The Apache WSGI application group this call was made on.",
example="de")
versions = fields.Dict(description="Some version numbers",
example={"checkmk": "1.8.0p1"})
edition = fields.String(description="The Checkmk edition.", example="raw")
demo = fields.Bool(description="Whether this is a demo version or not.",
example=False)
class InputPassword(BaseSchema):
ident = PasswordIdent(
example="pass",
description="An unique identifier for the password",
should_exist=False,
)
title = fields.String(
required=True,
example="Kubernetes login",
description="A title for the password",
)
comment = fields.String(required=False,
example="Kommentar",
description="A comment for the password",
missing="")
documentation_url = fields.String(
required=False,
attribute="docu_url",
example="localhost",
description=
"An optional URL pointing to documentation or any other page. You can use either global URLs (beginning with http://), absolute local urls (beginning with /) or relative URLs (that are relative to check_mk/).",
missing="",
)
password = fields.String(
required=True,
example="password",
description="The password string",
)
owner = PasswordOwner(
example="admin",
description=
"Each password is owned by a group of users which are able to edit, delete and use existing passwords.",
required=True,
attribute="owned_by",
)
shared = fields.List(
PasswordShare(
example="all",
description=
"By default only the members of the owner contact group are permitted to use a a configured password. It is possible to share a password with other groups of users to make them able to use a password in checks.",
),
example=["all"],
description="The list of members to share the password with",
required=False,
attribute="shared_with",
missing=[],
)
class CreateHostGroupDowntime(CreateDowntimeBase):
hostgroup_name = fields.String(
required=True,
description=param_description(schedule_hostgroup_host_downtime.__doc__, 'hostgroup_name'),
example='Servers',
)
duration = HOST_DURATION
class HostParameters(BaseSchema):
"""All the parameters for the hosts list.
Examples:
>>> p = HostParameters()
>>> p.load({})['columns']
['name']
>>> p.load({})['sites']
[]
"""
sites = fields.List(
fields.String(),
description="Restrict the query to this particular site.",
missing=[],
)
query = fields.query_field(Hosts, required=False)
columns = fields.List(
fields.LiveStatusColumn(
table=Hosts,
mandatory=[Hosts.name.name],
required=True,
),
description=("The desired columns of the hosts table. "
"If left empty, only the name column is used."),
missing=[Hosts.name.name],
required=False,
)
class AcknowledgeHostProblem(BaseSchema):
sticky = fields.Boolean(
required=False,
missing=False,
example=False,
description=param_description(acknowledge_host_problem.__doc__,
'sticky'),
)
persistent = fields.Boolean(
required=False,
missing=False,
example=False,
description=param_description(acknowledge_host_problem.__doc__,
'persistent'),
)
notify = fields.Boolean(
required=False,
missing=False,
example=False,
description=param_description(acknowledge_host_problem.__doc__,
'notify'),
)
comment = fields.String(
required=False,
missing="Acknowledged",
example='This was expected.',
description=param_description(acknowledge_host_problem.__doc__,
'comment'),
)
class DeleteDowntimeBase(BaseSchema):
delete_type = fields.String(
required=True,
description="The option how to delete a downtime.",
enum=['params', 'query'],
example="params",
)
class AcknowledgeSpecificServiceProblem(AcknowledgeServiceProblemBase):
service_description = fields.String(
description=
"The acknowledgement process will be applied to all matching service descriptions",
example="CPU load",
required=True,
)
class TimeRangeActive(BaseSchema):
day = fields.String(
description=
"The day for which time ranges are to be specified. The 'all' "
"option allows to specify time ranges for all days.",
pattern=f"all|{'|'.join(weekday_ids())}")
time_ranges = fields.List(fields.Nested(TimeRange))
class UpdateDiscoveryPhase(BaseSchema):
check_type = fields.String(
description='The name of the check which this service uses.',
example='df',
required=True,
)
service_item = fields.String(
description='The value uniquely identifying the service on a given host.',
example='/home',
required=True,
)
target_phase = fields.String(
description='The target phase of the service.',
enum=sorted(SERVICE_DISCOVERY_PHASES.keys()),
example='monitored',
required=True,
)
class LinkSchema(BaseSchema):
"""A Link representation according to A-24 (2.7)
"""
domainType = fields.Constant("link", required=True)
rel = fields.String(
description=
("Indicates the nature of the relationship of the related resource to the "
"resource that generated this representation"),
required=True,
example="self",
)
href = fields.Str(
description=
("The (absolute) address of the related resource. Any characters that are "
"invalid in URLs must be URL encoded."),
required=True,
example="https://.../api_resource",
)
method = fields.String(
description=
"The HTTP method to use to traverse the link (get, post, put or delete)",
required=True,
pattern="GET|PUT|POST|DELETE",
example="GET",
)
type = fields.String(
description="The content-type that the linked resource will return",
required=True,
example="application/json",
)
title = fields.String(
description=
("string that the consuming application may use to render the link without "
"having to traverse the link in advance"),
allow_none=True,
example="The object itself",
)
body_params = fields.Dict(
description=
("A map of values that shall be sent in the request body. If this is present,"
"the request has to be sent with a content-type of 'application/json'."
),
required=False,
)
class DomainObject(Linkable):
domainType: fields.Field = fields.String(
required=True,
description="The \"domain-type\" of the object.",
)
# Generic things to ease development. Should be changed for more concrete schemas.
id = fields.String(
description="The unique identifier for this domain-object type.", )
title = fields.String(
description="A human readable title of this object. Can be used for "
"user interfaces.", )
members = fields.Nested(
ObjectMemberDict(),
description=
"The container for external resources, like linked foreign objects or actions.",
)
extensions = fields.Dict(
description="All the attributes of the domain object.")
class DomainObjectCollection(Linkable):
id = fields.String(
description="The name of this collection.",
missing='all',
)
domainType: fields.Field = fields.String(
description="The domain type of the objects in the collection.")
title = fields.String(
description="A human readable title of this object. Can be used for "
"user interfaces.", )
value: fields.Field = fields.Nested(
CollectionItem,
description=
"The collection itself. Each entry in here is part of the collection.",
many=True,
)
extensions = fields.Dict(
description="Additional attributes alongside the collection.")
class ActionResultBase(Linkable):
resultType: fields.Field = fields.String(
enum=['object', 'scalar'],
description="The type of the result.",
)
extensions = fields.Dict(
example={'some': 'values'},
description="Some attributes alongside the result.",
)
class MoveFolder(BaseSchema):
destination = fields.String(
description=
("The folder-id of the folder to which this folder shall be moved to. May "
"be 'root' for the root-folder."),
pattern="[a-fA-F0-9]{32}|root",
example="root",
required=True,
)
class LinkSchema(BaseSchema):
"""A Link representation according to A-24 (2.7)
"""
domainType = fields.Constant("link", required=True)
rel = fields.String(
description=
("Indicates the nature of the relationship of the related resource to the "
"resource that generated this representation"),
required=True,
example="self",
)
href = fields.Str(
description=
("The (absolute) address of the related resource. Any characters that are "
"invalid in URLs must be URL encoded."),
required=True,
example="https://.../api_resource",
)
method = fields.String(
description=
"The HTTP method to use to traverse the link (get, post, put or delete)",
required=True,
pattern="GET|PUT|POST|DELETE",
example="GET",
)
type = fields.String(
description="The media type that the linked resource will return",
required=True,
example="application/json",
)
title = fields.String(
description=
("string that the consuming application may use to render the link without "
"having to traverse the link in advance"),
allow_none=True,
example="The object itself",
)
arguments = fields.Dict(
description=
("map that may be used as the basis for any data (arguments or properties) "
"required to follow the link."),
allow_none=True,
)
class CreateDowntimeBase(BaseSchema):
downtime_type = fields.String(
required=True,
description="The type of downtime to create.",
enum=[
'host', 'service', 'hostgroup', 'servicegroup', 'host_by_query',
'service_by_query'
],
example="host",
)
start_time = fields.DateTime(
format="iso8601",
required=True,
example="2017-07-21T17:32:28Z",
description=
"The start datetime of the new downtime. The format has to conform to the ISO 8601 profile",
)
end_time = fields.DateTime(
required=True,
example="2017-07-21T17:32:28Z",
description=
"The end datetime of the new downtime. The format has to conform to the ISO 8601 profile",
format="iso8601",
)
recur = fields.String(
required=False,
enum=[
"fixed", "hour", "day", "week", "second_week", "fourth_week",
"weekday_start", "weekday_end", "day_of_month"
],
description=param_description(schedule_host_downtime.__doc__, 'recur'),
example="hour",
missing="fixed",
)
duration = fields.Integer(
required=False,
description=param_description(schedule_host_downtime.__doc__,
'duration'),
example=3600,
missing=0,
)
comment = fields.String(required=False, example="Security updates")
class BulkDeleteContactGroup(BaseSchema):
# TODO: addition of etag field
entries = fields.List(
fields.String(
required=True,
description="The name of the contact group config",
example="windows",
),
required=True,
example=["windows", "panels"],
)
class AcknowledgeServiceProblemBase(BaseSchema):
acknowledge_type = fields.String(
required=True,
description="The acknowledge service selection type.",
enum=['service', 'servicegroup', 'service_by_query'],
example="service",
)
sticky = fields.Boolean(
required=False,
missing=True,
example=False,
description=param_description(acknowledge_service_problem.__doc__,
'sticky'),
)
persistent = fields.Boolean(
required=False,
missing=False,
example=False,
description=param_description(acknowledge_service_problem.__doc__,
'persistent'),
)
notify = fields.Boolean(
required=False,
missing=True,
example=False,
description=param_description(acknowledge_service_problem.__doc__,
'notify'),
)
comment = fields.String(
required=True,
example='This was expected.',
description=param_description(acknowledge_service_problem.__doc__,
'comment'),
)
class DiscoverServices(BaseSchema):
mode = fields.String(
description='''The mode of the discovery action. Can be one of:
* `new` - Add unmonitored services and new host labels
* `remove` - Remove vanished services
* `fix_all` - Add unmonitored services and new host labels, remove vanished services
* `refresh` - Refresh all services (tabula rasa), add new host labels
* `only_host_labels` - Only discover new host labels
''',
enum=list(DISCOVERY_ACTION.keys()),
example='refresh',
missing='fix_all',
)
class HostTag(BaseSchema):
ident = fields.String(required=False,
example="tag_id",
description="An unique id for the tag",
missing=None,
attribute="id")
title = fields.String(
required=True,
example="Tag",
description="The title of the tag",
)
aux_tags = fields.List(
AuxTag(
example="ip-v4",
description="An auxiliary tag id",
required=False,
),
description=
"The list of auxiliary tag ids. Built-in tags (ip-v4, ip-v6, snmp, tcp, ping) and custom defined tags are allowed.",
example=["ip-v4, ip-v6"],
required=False,
missing=[],
)
class ApiError(BaseSchema):
code = fields.Integer(
description="The HTTP status code.",
required=True,
example=404,
)
message = fields.Str(
description="Detailed information on what exactly went wrong.",
required=True,
example="The resource could not be found.",
)
title = fields.Str(
description="A summary of the problem.",
required=True,
example="Not found",
)
_fields = fields.Dict(
data_key='fields', # mypy
keys=fields.String(description="The field name"),
values=fields.List(fields.String(description="The error messages")),
description="Detailed error messages on all fields failing validation.",
required=False,
)
class CreateHostGroupDowntime(CreateDowntimeBase):
hostgroup_name = fields.String(
required=True,
description=param_description(schedule_hostgroup_host_downtime.__doc__, 'hostgroup_name'),
example='Servers',
)
include_all_services = fields.Boolean(
required=False,
description=param_description(schedule_hostgroup_host_downtime.__doc__,
'include_all_services'),
example=False,
missing=False,
)
duration = HOST_DURATION
