"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\nThe end result is a design using HATEOS principles where further\ninformation on a resource can be obatined by following the bread crumbs of the \nrelationships in the **.well-known/devops.json** file.\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.\n\nThe **devops.json** file has been defined using OpenAPI but that does not imply that\na real API needs to be deployed or used. On the contrary it is unlikely that the main\ncopy stored on Git is accessed via a API service. \n\nYou could build a catalogue service of all your **devops.json** definitions linked to\nGit definitions, but that is not a specification requirement.\n\nFor further information see https://github.com/meerkat-manor/rediOps",
"description":"This service will list the **devops** definitions registered \nwith it.\n\nThis definition is only applicable if the **deveops** is\npublished as a service outside of the source code.",
"description":"This service and its operations are intended for use where \nthe DevOps information from source versioning (e.g. Git)\nis wanted to be stored on a centrral registry.\n\nThe process of updating the central registry can be automated by use\nof web hooks which will retrieve the latest **.well-known/deveops.json**\nfrom Git on commits as an example.\n\nThis definition is only applicable if the **deveops** is\npublished as a service outside of the source code.",
"description":"The required Devops recor with the requested identity wasnot found."
}
},
"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-model"
}
}
},
"required":true
},
"responses":{
"200":{
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/devops-model"
}
}
},
"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":{
"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
}
]
},
"/health":{
"summary":"Fetch the health of the service",
"description":"The service will return either a 200 (OK) or a 503 error message\n\nThis definition is only applicable if the **deveops** is\npublished as a service outside of the source code.",
"get":{
"responses":{
"200":{
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/health-response"
},
"examples":{
"OK_state":{
"value":"\"OK\""
}
}
}
},
"description":"Returns the healthy message"
},
"503":{
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/health-response"
},
"examples":{
"ERROR_sample":{
"value":"\"ERROR\""
}
}
}
},
"description":"Service is not available"
}
}
}
},
"/.well-known/devops.json":{
"description":"This fetches the **devops.json\" file for this service,\n\nThis definition is only applicable if the **deveops** is\npublished as a service outside of the source code.",
"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."
"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.",
"description":"A configuration file that can be an URL location or a Git folder",
"type":"string"
},
"script":{
"description":"A script file that is executed to perform the activity.\n\nThe choice of processing engine is up to the organisation, or \nsome assumptions can be made based on file extension.\n\nFor example:\n\n* .sh = Bash\n* .ps1 = PowerShell\n* .bat = MS DOS command",
"description":"The dependency section provides information on:\n\n1. APIs that the service calls such as ODBC, Authentication, System of Record API\n2. Tools that are required for build, testing and deployment",
"type":"object",
"properties":{
"guide":{
"description":"Link to documentation on dependencies",
"description":"List of downstream dependency APIs.\n\nThe list can include:\n\n1. RESTful APIs\n2. SOAP APIs\n3. File transfer APIs\n4. ODBC or JDBC connections\n\nNo credentials are required to be captured in the definiton. Please do not include user names or passwords.",
"description":"Artefact engine\n\nSome common engines are:\n\n* Artifactory\n* Archiva\n\nCI servers can also have their own repository for generated artifact \n"
"description":"Source version control system engine.\n\nThis can be used by tools to retreive source code using binary executables.\n\nSome common tools are \"Git\", \"TFS\", \"Mercurial\", \"CVS\".",
"description":"The purpose of the tools section is an aid to identify the various tols required \nduring build, testing and deployment. This can server as a documentation item \nor actually preparing the nevironment to contain the necessary tool.\n\nIf you are using a well defined tool that is linked to your source versioning by\nweb hook then you are not likely to require this section for execution. \n\nA sample use case for a simple environment is to identify a tool that needs\nto be fetched from an artifact storage location as it is required by the \ndeployment install script.",
"type":"object",
"properties":{
"guide":{
"description":"Link to documentation for the tool in the context of this DevOps",
"description":"The processor to execute the commands.\n\nFor example you can define it as \"powershell\" to execute script file with extension .ps1\n\nYou cannot combine different commands for different processors in the one tools set. If you have different\nprocessors you can define multiple tools. ",
"description":"Provides information of the commands or scripts to use when\nthe resources is bing installed, refreshed or uninstalled.\n\nThe script or playbook can be sourced from the source version manager (e.g. Git)",
"description":"Lists the health services the resource exposes.\n\nThe guide can provide more detais about the health checks and their depth of checking.",
"type":"object",
"properties":{
"guide":{
"description":"Link to documentation describing the health check",
"description":"List of health check APIs published by the\nresource",
"type":"array",
"items":{
"$ref":"#/components/schemas/healthapi-model"
}
}
},
"example":{
"guide":"https://",
"api":[
{
"url":"/health",
"status":200,
"response":""
}
]
}
},
"healthapi-model":{
"title":"Root Type for healthapi-modle",
"description":"Describes the health service that the resource exposes.\n\nThe definition can inlcude expected response details",
"type":"object",
"properties":{
"url":{
"description":"URL for health check path. The path if suppied must\nmatch a path in the service definition (OpenAPI)\n\nUsing the URL path the details of the health check can\nbe found in the service definition.\n\nNormally a human coud make an intelligent assumption on\nwhat the name of the health check but a machine will find it\nmore difficult. Also consider how you would identify it \nin a foreign language.",
"type":"string"
},
"status":{
"format":"int32",
"description":"The HTTP status code for a successful health check.\n\n",
"type":"integer",
"example":"200"
},
"response":{
"description":"The expected response body from a healthy service",
"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.\nThe 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.",
"description":"A common name for the tool, such as:\n\n* makefile\n* teamcity\n* azure-pipeline\n\nThe choice is up to you but you should keep it consistent.",
"description":"A link to the 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":{
"guide":{
"description":"Link to documentation for the topic",
"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 possible values might be:\n\n* FILE for local or LAN based resources \n* S/FTP for FTP based URL resources",
"description":"A full URL for the API or if the value 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 used.",
"description":"Unique identifier \n\nThis is only applicable when the definition is serviced from a catalogue\nthat requires unique identifers.\n\nDo not use the Git repository URL as the unique identifier because\nto retrieve the file you would have to know the location. ",
"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",
"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.",
"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.",
"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.",
"description":"A link to documentation for the resource being \ndescribed by this document.\n\nThe preference is that the links is in the format of a HTTPS URL to a \nhuman readable web page.",
"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.",
"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.",
"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.",
"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.",
