2022-08-07 22:06:03 +00:00
|
|
|
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
|
