openapi: 3.0.0 info: title: Rediscover DevOps configuration version: v1 description: |- This document describes the specification of the proposed file **.well-known/devops.json** that can be used in the DevOps CI/cD as identifier for information required by the tools. By using the .well-known location, assumptions are reduced if not eliminated by the automation tools. Automation tools can also validate the information during source commit to confirm the engineers are providing the necessary information and that it is valid. contact: name: Meerkat url: 'https://github.com/meerkat-manor/rediOps' email: meerkat@merebox.com license: name: Apache 2.0 url: 'https://www.apache.org/licenses/LICENSE-2.0' paths: /.well-known/devops: get: responses: '200': content: application/json: schema: $ref: '#/components/schemas/devops' properties: version: type: string example: 0.0.1 created_on: type: string example: '2022-03-04T15:43:21Z' updated_on: type: string example: '2022-03-04T15:43:21Z' organisation: type: string example: Meerkat Manor Tech College name: type: string example: Web site asset_id: type: string example: AID07828923 owner: type: object properties: email: type: string example: devops@meerkatmanor-tech.org web: type: string example: meerkatmanor-tech.org slack: type: string example: '' twitter: type: string example: '' matrix: type: string example: '@devops:meerkat-manor.org' guide: type: string example: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' repository: type: object properties: guide: type: string example: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' source: type: string example: 'https://github.com' artefact: type: string example: '' dependency: type: object properties: guide: type: string example: '' apis: type: array items: type: object properties: asset_id: type: string example: AI560003 protocol: type: string example: ODBC url: type: string example: '' tools: type: array items: {} build: type: object properties: guide: type: string example: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: type: string example: JENKINS test: type: object properties: guide: type: string example: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: type: string example: UNITTEST api: type: array items: type: string example: api/v1/openapispec.json health: type: object properties: guide: type: string example: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' api: type: array items: type: object properties: url: type: string example: /health status: type: integer example: 200 response: type: string example: '' install: type: object properties: guide: type: string example: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: type: string example: ANSIBLE playbook: type: string example: '' commands: type: object properties: pre: type: array items: type: string example: hostname script: type: string example: deploy/install.sh post: type: array items: type: string example: echo Bye Bye refresh: type: object properties: guide: type: string example: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: type: string example: COMMAND playbook: type: string example: '' commands: type: object properties: pre: type: array items: {} script: type: string example: deploy/refresh.sh post: type: array items: type: string example: echo Refresh completed uninstall: type: object properties: guide: type: string example: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: type: string example: ANSIBLE playbook: type: string example: '' commands: type: object properties: pre: type: array items: {} script: type: string example: deploy/decomission.sh post: type: array items: type: string example: rm -R /opt/meerkat-manor/example examples: Demo: value: version: 0.0.1 created_on: '2022-03-04T15:43:21Z' updated_on: '2022-03-04T15:43:21Z' organisation: Meerkat Manor Tech College name: Web site asset: id: AID07828923 name: '' url: '' owner: email: devops@meerkatmanor-tech.org web: meerkatmanor-tech.org slack: '' twitter: '' matrix: '@devops:meerkat-manor.org' guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' repository: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' source-engine: Git source: 'https://github.com' artefact: '' dependency: guide: '' apis: - asset_id: AI560003 protocol: ODBC url: '' - asset_id: AI560044 protocol: REST url: '' tools: [] build: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: JENKINS test: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: UNITTEST api: - engine: REST url: api/v1/openapispec.json - engine: REST url: api/v2/openapispec.json health: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' api: - url: /health status: 200 response: '' install: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: ANSIBLE playbook: '' commands: pre: - hostname - whoami script: deploy/install.sh post: - echo Bye Bye refresh: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: COMMAND playbook: '' commands: pre: [] script: deploy/refresh.sh post: - echo Refresh completed uninstall: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: ANSIBLE playbook: '' commands: pre: [] script: deploy/decomission.sh post: - rm -R /opt/meerkat-manor/example - echo Component removed description: '' security: - {} summary: Fetch the DevOps information description: >- Commonly the DevOps information is not fetched using a REST API but is actually the JSON file stored the root **.well-known** directory as the file name **devops.json** If so required there can be a supporting REST API to fetch the contents, but that is not the primary intent. /devops: get: responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/devops' description: Listing matching resources '404': description: No match for resource or no resources exist security: - {} parameters: - name: id description: List resources with matching asset id schema: type: string in: query - name: name description: List resources matchin on name schema: type: string in: query '/devops/{id}': summary: Operate on the identified resources get: parameters: - name: id description: |- Identifier for the DevOps resource. The identifier is the Asset Id which is asumed to be unique for the catalogue servce. schema: type: string in: path required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/devops' description: The DevOps record was found '404': description: The required Devops recor with the requested identity wasnot found. security: - {} summary: Fetch the Devops resource description: |- For web servers that provide a DevOps catalogue,this service fetches the details for the requested DevOps identity post: requestBody: content: application/json: schema: $ref: '#/components/schemas/devops' required: true parameters: - name: id description: |- Identifer of the DevOps resource. This must match the asset identifier and is unique across all DevOps. schema: type: string in: path required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/devops' description: |- The updated record is returned to the caller on succssful update security: - BearerAuthentication: [] summary: Update the DevOps resource description: |- This service is for servers providing a catalogue service for DevOps information. The original Git details are not required to be updated. You could create a capability where this POST is used to update the source details and commit those changes. delete: parameters: - name: id description: Resource identifier for resource to be deleted schema: type: string in: path required: true responses: '200': description: Resource successfully deleted. '401': description: Not authorised to delete resource '404': description: Resource not fouund security: - BearerAuthentication: [] parameters: - examples: Sample: value: '"AI7842389-01"' name: id description: Resource identifier schema: type: string in: path required: true components: schemas: devops-action: title: Root Type for devops-action description: '' type: object properties: guide: type: string engine: enum: - ANSIBLE - COMMANDS type: string playbook: type: string commands: $ref: '#/components/schemas/commands' properties: pre: type: array items: type: string script: type: string post: type: array items: type: string example: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: ANSIBLE playbook: '' commands: pre: - hostname - whoami script: deploy/install.sh post: - echo Bye Bye commands: title: Root Type for commands description: >- Commands are executed by the engine. The commands need to be constructed in a format compatible with the engine. type: object properties: pre: description: Commands if any that are executed before the script and post items. type: array items: type: string script: description: |- A single script thais executed after the "pre" and before the "post" commands. The script can be an URL or a file within the version control (e.g. Git) repository. type: string post: description: Commands if any that are executed after the script. type: array items: type: string example: pre: - hostname - whoami script: /deploy/install.sh post: - echo Bye Bye owner-contact: title: Root Type for asset-owner description: |- The name and /or contact detals of the DevOps owner. The owner can be a single person or a team. It is preferale thati t is more granualr then the organisation. If you have a CMDB catalgue then the entry here should match the details on the CMDB if you choose to include them here. The contact details do not include a phone / mobile / cell number on purpose as this information is either know by the reader for the person / team or can be obtained from an organisations internal directory. Automated tools are unlikely to benefit from having access to a phone number, but they can send emails or post messages to Slack. type: object properties: email: description: |- The email adress of the owner. The email address could be a distribution list. minLength: 6 pattern: >- ([-!#-'*+/-9=?A-Z^-~]+(\.[-!#-'*+/-9=?A-Z^-~]+)*|"([]!#-[^-~ \t]|(\\[\t -~]))+")@([0-9A-Za-z]([0-9A-Za-z-]{0,61}[0-9A-Za-z])?(\.[0-9A-Za-z]([0-9A-Za-z-]{0,61}[0-9A-Za-z])?)*|\[((25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(\.(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])){3}|IPv6:((((0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):){6}|::((0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):){5}|[0-9A-Fa-f]{0,4}::((0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):){4}|(((0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):)?(0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}))?::((0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):){3}|(((0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):){0,2}(0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}))?::((0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):){2}|(((0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):){0,3}(0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}))?::(0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):|(((0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):){0,4}(0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}))?::)((0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):(0|[1-9A-Fa-f][0-9A-Fa-f]{0,3})|(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(\.(25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])){3})|(((0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):){0,5}(0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}))?::(0|[1-9A-Fa-f][0-9A-Fa-f]{0,3})|(((0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}):){0,6}(0|[1-9A-Fa-f][0-9A-Fa-f]{0,3}))?::)|(?!IPv6:)[0-9A-Za-z-]*[0-9A-Za-z]:[!-Z^-~]+)]) type: string web: description: |- A web page URL for the owner. The web page could refer to a team page. type: string slack: description: Slack address of the owner. type: string twitter: type: string matrix: description: The matrrix IM identfier of the owner type: string name: description: |- The name of the owner. This may be persons or teams name. type: string example: email: devops@meerkatmanor-tech.org web: meerkatmanor-tech.org slack: '' twitter: '' matrix: '@devops:meerkat-manor.org' asset-id: title: Root Type for asset-id description: '' type: object properties: id: type: string name: type: string url: type: string example: id: AID07828923 name: devops url: '' devops: title: Root Type for devops description: Information that supports DevOps activity. required: - version - name type: object properties: version: description: |- Specification version Major versions may not be compatible with minor versions. type: string example: 0.1.34 created_on: format: date-time description: |- Date and time this content was first created. The formatt is in ISO8061 and includes the date and time type: string example: '2022-05-29T13:44:11.000Z' updated_on: format: date-time description: >- Date this content was last updated. If retrieved from source version control (e.g. Git) then the value here should match the Git commit date for file. The formatt is in ISO8061 and includes the date and time type: string example: '2022-07-25T17:22:11.00Z' organisation: description: |- The name of the organisation that owns the implemened resouurce. The owner may not be netllectual Property / Copyright owner as the general detaisl about the resource may be in teh public domain or this organisation has licensed the rightsto use the resource and its secification. type: string name: description: |- A name for the resource this document covers. If there is a CMDB catalogue then the name here should match the name on the CMDB. maxLength: 100 minLength: 5 type: string example: Ecommeerce web site asset: $ref: '#/components/schemas/asset-id' description: >- Rsource information that is intended to be related to a Computer Management Database (CMDB). By linking to the asset in an CMDB, further information can be retrieved. If the CMDB link exists then it should be considered the authorative source where the same information exists in this definition. If you wish the DevOps workflow to control the information and be versioned with Git, then you can use this information to push updates to the CMDB. Just include processing of the __./well-known/devops.json__ into your deployment pipeline and post to the CMDB the updates. example: "{\r\n \"id\": \"AID07828923\",\r\n \"name\": \"devops\",\r\n \"url\": \"\"\r\n}" owner: $ref: '#/components/schemas/owner-contact' description: |- Contact information for the resource being described. If the resorce information is provided from a central source such as a CMDB then this content should match. properties: email: type: string web: type: string slack: type: string twitter: type: string matrix: type: string guide: description: |- A link to documentation for the resource being described by this document. The preferece is that the links is in the format of a HTTPS URL to a human readable web page. type: string repository: description: Repository links type: object properties: guide: type: string source: type: string artefact: type: string dependency: type: object properties: guide: type: string apis: type: array items: type: object properties: asset_id: type: string protocol: type: string url: type: string tools: type: array items: {} build: $ref: '#/components/schemas/activity' description: 'Describes the build process, configuration and script file' properties: guide: type: string engine: type: string test: $ref: '#/components/schemas/activity' description: 'Describes the test process, tools and script' properties: guide: type: string engine: type: string health: description: |- Information on the health service(s0 supported by the resource being described in this document. type: object properties: guide: type: string api: type: array items: type: object properties: url: type: string status: format: int32 type: integer response: type: string install: $ref: '#/components/schemas/devops-action' description: |- The Install section gives information on installing the resource onto a server for the first time. The detection on whether the resource is already installed is not defined in the specifications. The information can be in the form of an Ansibe playbook or commands to be executed on the server. You can also execute commaonds from a script file that is found on the Git repo. properties: guide: type: string engine: type: string playbook: type: string commands: type: object properties: pre: type: array items: type: string script: type: string post: type: array items: type: string refresh: $ref: '#/components/schemas/devops-action' description: |- The Refresh section gives information on refreshing the resource on the server. The instructions can be the same as for installing the first time. The information can be in the form of a Ansibe playbook or commands to be executed on the server with the component installed. You can also execute commaonds from a script file that is found on the Git repo. properties: guide: type: string engine: type: string playbook: type: string commands: type: object properties: pre: type: array items: {} script: type: string post: type: array items: type: string uninstall: $ref: '#/components/schemas/devops-action' description: |- The Uninstall section gives information on uninstalling the component. The information can be in the form of an Ansibe playbook or commands to be executed on the server with the component installed. You can also execute commaonds from a script file that is found on the Git repo. properties: guide: type: string engine: type: string playbook: type: string commands: type: object properties: pre: type: array items: {} script: type: string post: type: array items: type: string apis: description: >- List of OpenAPI definitions. The list can include Git and REST versions, because before build the API might not be available as a REST service. A resource may have multiple definitions files or even different versions. type: array items: $ref: '#/components/schemas/api' example: version: 0.0.1 created_on: '2022-03-04T15:43:21Z' updated_on: '2022-03-04T15:43:21Z' organisation: Meerkat Manor Tech College name: Web site asset: id: AID07828923 name: website url: '' owner: email: devops@meerkatmanor-tech.org web: meerkatmanor-tech.org slack: '' twitter: '' matrix: '@devops:meerkat-manor.org' guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' repository: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' source-engine: Git source: 'https://github.com' artefact: '' dependency: guide: '' apis: - asset_id: AI560003 protocol: ODBC url: '' - asset_id: AI560044 protocol: REST url: '' tools: [] build: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: JENKINS test: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: UNITTEST api: - api/v1/openapispec.json - api/v2/openapispec.json health: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' api: - url: /health status: 200 response: '' install: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: ANSIBLE playbook: '' commands: pre: - hostname - whoami script: deploy/install.sh post: - echo Bye Bye refresh: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: COMMAND playbook: '' commands: pre: [] script: deploy/refresh.sh post: - echo Refresh completed uninstall: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' engine: ANSIBLE playbook: '' commands: pre: [] script: deploy/decomission.sh post: - rm -R /opt/meerkat-manor/example - echo Component removed repository: title: Root Type for repository description: |- Link information to repositories for various registeries. You can add custom extensions with prefix **x-** type: object properties: guide: description: Link tgo documentation on repositories used by this component type: string source-engine: description: |- Source control version engine. This can be used by tools to retreive source code using binary executables. Some common tools are "Git", "TFS", "Mercurial", "CVS". type: string example: Git source: description: |- Link to source version control system, such as Git. The version control engine will provide the source version control system. type: string artefact-engine: type: string artefact: type: string example: guide: 'https://sku61.atlassian.net/wiki/spaces/WELLKNOWN/overview' source-engine: Git source: 'https://github.com' artefact-engine: Archiva artefact: '' api: title: Root Type for api description: |- An API definition in OpenAPI format. The definition file can be source from various locations, with the most commo being either Git or REST (HTTPS) accessible locations. A Git file can be accessed with Git command while REST / HTTPS might use the "wget" or "curl" commands required: - engine - url type: object properties: engine: description: |- The engine that the Url refers to. As the Url format is used by various processors, an engine value is required for proper processing. The acceptable values will depend on the organisation, but the minimal values that need to be supported are: * GIT for Git located resources. For this case the Git resource is assumed to be in the Git repository for this DevOps resource if the prefix is not HTTPS * REST for HTTP/S based web pages that are no explicitly handled by other engines Other ppssible values might be: * FILE for loca or LAN based resources * S/FTP for FTP based URL resources maxLength: 20 type: string url: description: |- A full URL for the API or if the valu is partial then the location is assumed to be on the Git repo. That is the host name and Git name are the same as for the "devops.json" file. If the resource details are being supplied by a catalogu service then the value in the "repository" section will be ued. maxLength: 500 type: string example: engine: REST url: api/v1/openapispec.json activity: title: Root Type for activity description: '' type: object properties: guide: type: string engine: type: string config: type: string script: type: string example: guide: 'https://' engine: JENKINS config: /build/jenkins-build.conf script: /build/builder.sh securitySchemes: BearerAuthentication: scheme: bearer type: http tags: - name: Published description: API has been deployed and is available for consumption - name: Development description: 'API has been specified, but it is still in development and may change' - name: Drafted description: API has been drafted but is subject to change - name: Proposed description: API has been proposed but no specification has been drafted