diff --git a/README.md b/README.md index 164e543..ecc325f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # rediOps -Rediscover DeveOps is about standardising how to find information about the code, specifically for use in the DevOps pipeline and +Rediscover DevOps is about standardising how to find information about the code, specifically for use in the DevOps pipeline and for engineers to locate relavant information about the code and its capability and DevOps process. The information resides with the code in the code repository, commonly Git, and is human readable and also understood by tools. @@ -26,9 +26,12 @@ for other files or actions to perform. ## Specification The specification for the **devops.json** is defined as an OpenAPI document allowing the publishing -of hte information also as a REST service if so required - though this is not mandatory - and +of the information also as a REST service if so required - though this is not mandatory - and the "devops.json" file is expected to exist before the code is deployed. +The use of OpenAPI to define the details specification provides a format and protocol that can be understood +by tools and engineers. There a few aspects of the specifications that cannot be documented in OpenAPI. + If you do publish the information as a REST service then you should consider protecting access to the data, especially if it contains data that may expose internal structures. diff --git a/specification/rediops.json b/specification/rediops.json index 31c9e7c..b6daaa5 100644 --- a/specification/rediops.json +++ b/specification/rediops.json @@ -2,7 +2,17 @@ "openapi": "3.0.0", "info": { "title": "Rediscover DevOps configuration", - "version": "v1" + "version": "v1", + "description": "This document describes the specification of the \nproposed file **.well-known/devops.json** that can \nbe used in the DevOps CI/cD as identifier for\ninformation required by the tools.\n\nBy using the .well-known location, assumptions are\nreduced if not eliminated by the automation tools.\n\nAutomation tools can also validate the information during \nsource commit to confirm the engineers are providing the necessary \ninformation 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": { @@ -423,9 +433,186 @@ "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**\n\nIf so required there can be a supporting REST API to fetch the contents, but that is not the primary intent." } + }, + "/devops": { + "get": { + "responses": { + "404": { + "description": "No match for resource or no resources exist" + }, + "200": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/devops" + } + } + } + }, + "description": "Listing matching resources" + } + }, + "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.\n\nThe 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\nfetches 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.\n\nThis 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\non succssful update" + } + }, + "security": [ + { + "BearerAuthentication": [ + ] + } + ], + "summary": "Update the DevOps resource", + "description": "This service is for servers providing a catalogue service\nfor DevOps information. The original Git details are not required to\nbe updated.\n\nYou could create a capability where this POST is used to \nupdate 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." + }, + "404": { + "description": "Resource not fouund" + }, + "401": { + "description": "Not authorised to delete resource" + } + }, + "security": [ + { + "BearerAuthentication": [ + ] + } + ] + }, + "parameters": [ + { + "examples": { + "Sample": { + "value": "\"AI7842389-01\"" + } + }, + "name": "id", + "description": "Resource identifier", + "schema": { + "type": "string" + }, + "in": "path", + "required": true + } + ] } }, "components": { @@ -522,22 +709,32 @@ }, "owner-contact": { "title": "Root Type for asset-owner", - "description": "", + "description": "The name and /or contact detals of the DevOps owner.\n\nThe owner can be a single person or a team. It is preferale thati t is more\ngranualr then the organisation.\n\nIf you have a CMDB catalgue then the entry here should match the details on\nthe CMDB if you choose to include them here.\n\nThe contact details do not include a phone / mobile / cell number on purpose\nas this information is either know by the reader for the person / team or\ncan be obtained from an organisations internal directory.\n\nAutomated tools are unlikely to benefit from having access to a phone number, but they\ncan send emails or post messages to Slack.", "type": "object", "properties": { "email": { + "description": "The email adress of the owner.\n\nThe 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.\n\nThe 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.\n\nThis may be persons or teams name.", "type": "string" } }, @@ -573,33 +770,48 @@ "devops": { "title": "Root Type for devops", "description": "Information that supports DevOps activity.", + "required": [ + "version", + "name" + ], "type": "object", "properties": { "version": { - "type": "string" + "description": "Specification version\n\nMajor versions may not be compatible with minor versions.", + "type": "string", + "example": "0.1.34" }, "created_on": { "format": "date-time", - "type": "string" + "description": "Date and time this content was first created.\n\nThe formatt is in ISO8061 and includes the date and time", + "type": "string", + "example": "2022-05-29T13:44:11.000Z" }, "updated_on": { "format": "date-time", - "type": "string" + "description": "Date this content was last updated.\n\nIf retrieved from source version control (e.g. Git) then the value here should match the \nGit commit date for file.\n\nThe 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.\n\nThe owner may not be netllectual Property / Copyright owner as the\ngeneral detaisl about the resource may be in teh public domain or\nthis organisation has licensed the rightsto use the resource\nand its secification.", "type": "string" }, "name": { - "type": "string" + "description": "A name for the resource this document covers.\n\nIf there is a CMDB catalogue then the name here should match the\nname on the CMDB.", + "maxLength": 100, + "minLength": 5, + "type": "string", + "example": "Ecommeerce web site" }, "asset": { "$ref": "#/components/schemas/asset-id", - "description": "Asset information that is intended to be related to a Computer Management Database (CMDB).\n\nBy linking to the asset in an CMDB further information can be retrieved.\n\nIf the CMDB link exists then it should be considered the authorative source where the same information exists in this definition.\n\nIf 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.", + "description": "Rsource information that is intended to be related to a Computer Management Database (CMDB).\n\nBy linking to the asset in an CMDB, further information can be retrieved.\n\nIf the CMDB link exists then it should be considered the authorative source where the same information exists in this definition.\n\nIf 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 asset / artifact being described.\n\nIf the asset information is provided from a central source then this content should match.", + "description": "Contact information for the resource being described.\n\nIf the resorce information is provided from a central source\nsuch as a CMDB then this content should match.", "properties": { "email": { "type": "string" @@ -619,6 +831,7 @@ } }, "guide": { + "description": "A link to documentation for the resource being \ndescribed by this document.\n\nThe preferece is that the links is in the format of a HTTPS URL to a \nhuman readable web page.", "type": "string" }, "repository": { @@ -668,7 +881,8 @@ } }, "build": { - "type": "object", + "$ref": "#/components/schemas/activity", + "description": "Describes the build process, configuration and script file", "properties": { "guide": { "type": "string" @@ -679,7 +893,8 @@ } }, "test": { - "type": "object", + "$ref": "#/components/schemas/activity", + "description": "Describes the test process, tools and script", "properties": { "guide": { "type": "string" @@ -690,6 +905,7 @@ } }, "health": { + "description": "Information on the health service(s0 supported\nby the resource being described in this document.", "type": "object", "properties": { "guide": { @@ -717,6 +933,7 @@ }, "install": { "$ref": "#/components/schemas/devops-action", + "description": "The Install section gives information on installing the resource onto a server\nfor the first time. The detection on whether the resource is already\ninstalled is not defined in the specifications.\n\nThe information can be in the form of an Ansibe playbook or commands to \nbe executed on the server. You can also execute \ncommaonds from a script file that is found on the Git repo.", "properties": { "guide": { "type": "string" @@ -751,6 +968,7 @@ }, "refresh": { "$ref": "#/components/schemas/devops-action", + "description": "The Refresh section gives information on refreshing the resource on the server. \nThe instructions can be the same as for installing the first time.\n\nThe information can be in the form of a Ansibe playbook or commands to \nbe executed on the server with the component installed. You can also execute \ncommaonds from a script file that is found on the Git repo.", "properties": { "guide": { "type": "string" @@ -785,6 +1003,7 @@ }, "uninstall": { "$ref": "#/components/schemas/devops-action", + "description": "The Uninstall section gives information on uninstalling the component.\n\nThe information can be in the form of an Ansibe playbook or commands to \nbe executed on the server with the component installed. You can also execute \ncommaonds from a script file that is found on the Git repo.", "properties": { "guide": { "type": "string" @@ -818,7 +1037,7 @@ } }, "apis": { - "description": "List of OpenAPI definitions.\n\nThe list can include Git and REST versions, because before build the API might not be available\nas a REST service.", + "description": "List of OpenAPI definitions.\n\nThe list can include Git and REST versions, because before build the API might not be available\nas a REST service.\n\nA resource may have multiple definitions files or even different versions.", "type": "array", "items": { "$ref": "#/components/schemas/api" @@ -846,6 +1065,7 @@ "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": "" }, @@ -967,13 +1187,78 @@ }, "api": { "title": "Root Type for api", - "description": "", - "type": "string", + "description": "An API definition in OpenAPI format.\n\nThe definition file can be source from various locations, with\nthe most commo being either Git or REST (HTTPS) accessible \nlocations.\n\nA Git file can be accessed with Git command while REST / HTTPS\nmight 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 \nprocessors, an engine value is required for proper processing.\n\nThe acceptable values will depend on the organisation, but the\nminimal values that need to be supported are:\n\n* GIT for Git located resources. For this case the Git resource is assumed \n to be in the Git repository for this DevOps resource if the prefix is not\n HTTPS\n* REST for HTTP/S based web pages that are no explicitly handled by other engines\n\nOther ppssible values might be:\n\n* FILE for loca or LAN based resources \n* 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\nthen the location is assumed to be on the Git repo. That is the host name and\nGit name are the same as for the \"devops.json\" file.\n\nIf the resource details are being supplied by a catalogu service\nthen 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" + } + ] } \ No newline at end of file diff --git a/specification/rediops.yaml b/specification/rediops.yaml index e69de29..bd28835 100644 --- a/specification/rediops.yaml +++ b/specification/rediops.yaml @@ -0,0 +1,1057 @@ +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