Skip to content

ED: Complement data.image with RUNTIME_ENVIRONMENT link type #264

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 16, 2021
Merged

ED: Complement data.image with RUNTIME_ENVIRONMENT link type #264

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<!---
Copyright 2017-2018 Ericsson AB.
Copyright 2017-2021 Ericsson AB and others.
For a full list of individual contributors, please see the commit history.

Licensed under the Apache License, Version 2.0 (the "License");
Expand All @@ -18,7 +18,7 @@
# EiffelEnvironmentDefinedEvent (ED)
The EiffelEnvironmentDefinedEvent declares an environment which may be referenced from other events in order to secure traceability to the conditions under which an artifact was created or a test was executed. Depending on the technology domain, the nature of an environment varies greatly however: it may be a virtual image, a complete mechatronic system of millions of independent parts, or anything in between. Consequently, a concise yet complete and generic syntax for describing any environment is futile.

From Eiffel's point of view, however, the prioritized concern is not _description_ of the environment, but rather unambiguous _identification_ of it. Consequently, the EiffelEnvironmentDefinedEvent syntax offers several alternatives to be selected from depending on the use case at hand: an environment may be described using __data.image__, __data.host__ or __data.uri__. Exactly one of these properties SHOULD be included in any one event. In certain situations where an actual description of the environment is deemed redundant or its nature is implicit, the event MAY be used without any of these properties; it should be noted, however, that _explicit_ practices are always encouraged over _implicit_ ones.
From Eiffel's point of view, however, the prioritized concern is not _description_ of the environment, but rather unambiguous _identification_ of it. Consequently, the EiffelEnvironmentDefinedEvent syntax offers several alternatives to be selected from depending on the use case at hand: an environment may be described using __data.image__, __data.host__ or __data.uri__, or a __RUNTIME_ENVIRONMENT__ link to another event that provides a more comprehensive description. Unless a link of the latter kind is used exactly one of these properties SHOULD be included in any one event. In certain situations where an actual description of the environment is deemed redundant or its nature is implicit, the event MAY be used without any of these properties or a RUNTIME_ENVIRONMENT link; it should be noted, however, that _explicit_ practices are always encouraged over _implicit_ ones.

## Data Members
### data.name
Expand All @@ -34,7 +34,7 @@ __Description:__ The version of the environment, if any. This is in a sense redu
### data.image
__Type:__ String
__Required:__ No
__Description:__ A string identifying e.g. a [Docker](https://www.docker.com/) image. While not a perfect description of an environment, in many cases it is both sufficient and conducive.
__Description:__ A string identifying e.g. a [Docker](https://www.docker.com/) image that defines this environment. Use of this member is discouraged. Prefer using the less ambiguous RUNTIME_ENVIRONMENT link type.

### data.host
__Type:__ Object
Expand Down Expand Up @@ -82,6 +82,12 @@ __Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFl
__Multiple allowed:__ Yes
__Description:__ Identifies the flow context of the event: which is the continuous integration and delivery flow in which this occurred – e.g. which product, project, track or version this is applicable to.

### RUNTIME_ENVIRONMENT
__Required:__ No
__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md), [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md)
__Multiple allowed:__ Yes
__Description:__ Identifies a description of a runtime environment within which an activity has taken place. The target event could e.g. identify a [Docker](https://www.docker.com/) image, a JVM distribution archive, or a composition of operating system packages that were installed on the host system. This link type has the same purpose as the `data.image` member but allows richer and less ambiguous descriptions.

## Meta Members
### meta.id
__Type:__ String
Expand Down Expand Up @@ -211,6 +217,7 @@ __Description:__ The number of the event within the named sequence.
## Version History
| Version | Introduced in | Changes |
| --------- | ------------------------------------------------------ | --------------------------------------- |
| 3.1.0 | Current version | Added RUNTIME_ENVIRONMENT link type. |
| 3.0.0 | [edition-agen](../../../tree/edition-agen) | Improved information integrity protection | (see [Issue 185](https://github.com/eiffel-community/eiffel/issues/185)) |
| 2.0.0 | [dc5ec6f](../../../blob/dc5ec6fb87e293eeffe88fdafe698eec0f5a2c89/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. |
Expand All @@ -220,3 +227,4 @@ __Description:__ The number of the event within the named sequence.
* [URI example](../examples/events/EiffelEnvironmentDefinedEvent/uri.json)
* [Host example](../examples/events/EiffelEnvironmentDefinedEvent/host.json)
* [Image example](../examples/events/EiffelEnvironmentDefinedEvent/image.json)
* [RUNTIME_ENVIRONMENT link example](../examples/events/EiffelEnvironmentDefinedEvent/runtime-env-link.json)
25 changes: 25 additions & 0 deletions examples/events/EiffelEnvironmentDefinedEvent/runtime-env-link.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{
"meta": {
"type": "EiffelEnvironmentDefinedEvent",
"version": "3.1.0",
"time": 1234567890,
"id": "aaaaaaaa-bbbb-5ccc-8ddd-eeeeeeeeeee0",
"source": {
"host": "envmanager.internal.myorg.org"
}
},
"data": {
"name": "John's Docker Environment",
"version": "2.10.3"
},
"links": [
{
"type": "PREVIOUS_VERSION",
"target": "aaaaaaaa-bbbb-5ccc-8ddd-eeeeeeeeeee1"
},
{
"type": "RUNTIME_ENVIRONMENT",
"target": "aaaaaaaa-bbbb-5ccc-8ddd-eeeeeeeeeee2"
}
]
}
194 changes: 194 additions & 0 deletions schemas/EiffelEnvironmentDefinedEvent/3.1.0.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,194 @@
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
},
"type": {
"type": "string",
"enum": [ "EiffelEnvironmentDefinedEvent" ]
},
"version": {
"type": "string",
"enum": [ "3.1.0" ],
"default": "3.1.0"
},
"time": {
"type": "integer"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "object",
"properties": {
"domainId": {
"type": "string"
},
"host": {
"type": "string"
},
"name": {
"type": "string"
},
"serializer": {
"type": "string",
"pattern": "^pkg:"
},
"uri": {
"type": "string"
}
},
"additionalProperties": false
},
"security": {
"type": "object",
"properties": {
"authorIdentity": {
"type": "string"
},
"integrityProtection": {
"type": "object",
"properties": {
"signature": {
"type": "string"
},
"alg": {
"type": "string",
"enum": ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512"]
},
"publicKey": {
"type": "string"
}
},
"required": [
"signature",
"alg"
],
"additionalProperties": false
},
"sequenceProtection": {
"type": "array",
"items": {
"type": "object",
"properties": {
"sequenceName": {
"type": "string"
},
"position": {
"type": "integer"
}
},
"additionalProperties": false,
"required": [
"sequenceName",
"position"
]
}
}
},
"additionalProperties": false,
"required": [
"authorIdentity"
]
}
},
"required": [
"id",
"type",
"version",
"time"
],
"additionalProperties": false
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"version": {
"type": "string"
},
"image": {
"type": "string"
},
"host": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"user": {
"type": "string"
}
},
"required": [
"name",
"user"
],
"additionalProperties": false
},
"uri": {
"type": "string"
},
"customData": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"value": {
}
},
"required": [
"key",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"name"
],
"additionalProperties": false
},
"links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"target": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
}
},
"required": [
"type",
"target"
],
"additionalProperties": false
}
}
},
"required": [
"meta",
"data",
"links"
],
"additionalProperties": false
}