Skip to content
New issue

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

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

Already on GitHub? Sign in to your account

added section for devfile library #111

Merged
merged 4 commits into from
Dec 2, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/modules/user-guide/nav.adoc
Original file line number Diff line number Diff line change
@@ -29,6 +29,9 @@
*** xref:adding-event-bindings.adoc[]
*** xref:referring-to-a-parent-devfile-in-a-devfile.adoc[]

** xref:devfile-library.adoc[]
*** xref:using-the-devfile-library.adoc[]
* Registry Administrator
** xref:devfile-registry.adoc[]
6 changes: 6 additions & 0 deletions docs/modules/user-guide/pages/devfile-library.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
:description: Devfile library
:navtitle: Devfile library
:keywords: devfile, library


include::partial$assembly_devfile-library.adoc[]
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
:description: Using the devfile library
:navtitle: Using the devfile library
:keywords: devfile, library


include::partial$proc_using-the-devfile-library.adoc[]
6 changes: 6 additions & 0 deletions docs/modules/user-guide/pages/using-the-devfile-library.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
:description: Using the devfile library
:navtitle: Using the devfile library
:keywords: devfile, library


include::partial$proc_using-the-devfile-library.adoc[]
30 changes: 30 additions & 0 deletions docs/modules/user-guide/partials/assembly_devfile-library.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
ifdef::context[:parent-context-of-assembly_devfile-library: {context}]


ifndef::context[]
[id="assembly_devfile-library"]
endif::[]
ifdef::context[]
[id="assembly_devfile-library_{context}"]
endif::[]
= Devfile library

:context: assembly_devfile-library


[role="_abstract"]
Using the devfile library, you can:

* Validate a devfile.
* Parse a `devfile.yaml` file as specified by the devfile API reference.
* Write updated data to a `devfile.yaml` file.
* Generate Kubernetes objects for various devfile resources.
* Define the `util` functions for the devfile.
The library is written in Golang, and the following projects consume the library as a Golang dependency:

* Odo
* OpenShift Console
== Additional resources
* xref:using-the-devfile-library.adoc[]
153 changes: 153 additions & 0 deletions docs/modules/user-guide/partials/proc_using-the-devfile-library.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
[id="proc_using-the-devfile-library_{context}"]
= Using the devfile library

[role="_abstract"]
Using the devfile library, you can parse and write any devfile, helping you maintain consistent development environments and making it easier for teams to collaborate across shared projects.

.Procedure

* Parse a devfile by running:

====
----
// ParserArgs is the struct to pass into parser functions which contains required info for parsing devfile.
parserArgs := parser.ParserArgs{
Path: path,
FlattenedDevfile: &flattenedDevfile,
RegistryURLs: registryURLs,
DefaultNamespace: defaultNamespace,
Context: context,
K8sClient: client,
}
// Parses the devfile and validates the devfile data
// if top-level variables are not substituted successfully, the warnings can be logged by parsing variableWarning
devfile, variableWarning, err := devfilePkg.ParseDevfileAndValidate(parserArgs)
----
====

* Get specific content from a devfile by running:

====
----
// To get all the components from the devfile
components, err := devfile.Data.GetComponents(DevfileOptions{})
// To get all the components from the devfile with attributes tagged - tool: console-import
// & import: {strategy: Dockerfile}
components, err := devfile.Data.GetComponents(DevfileOptions{
Filter: map[string]interface{}{
"tool": "console-import",
"import": map[string]interface{}{
"strategy": "Dockerfile",
},
},
})
// To get all the volume components
components, err := devfile.Data.GetComponents(DevfileOptions{
ComponentOptions: ComponentOptions{
ComponentType: v1.VolumeComponentType,
},
})
// To get all the exec commands that belong to the build group
commands, err := devfile.Data.GetCommands(DevfileOptions{
CommandOptions: CommandOptions{
CommandType: v1.ExecCommandType,
CommandGroupKind: v1.BuildCommandGroupKind,
},
})
----
====

* Get the Kubernetes objects from the devfile by running:

====
----
// To get a slice of Kubernetes containers of type corev1.Container from the devfile component containers
containers, err := generator.GetContainers(devfile)
// To generate a Kubernetes deployment of type v1.Deployment
deployParams := generator.DeploymentParams{
TypeMeta: generator.GetTypeMeta(deploymentKind, deploymentAPIVersion),
ObjectMeta: generator.GetObjectMeta(name, namespace, labels, annotations),
InitContainers: initContainers,
Containers: containers,
Volumes: volumes,
PodSelectorLabels: labels,
}
deployment := generator.GetDeployment(deployParams)
----
====

* Update the devfile content by running:

====
----
// To update an existing component in the devfile object
err := devfile.Data.UpdateComponent(v1.Component{
Name: "component1",
ComponentUnion: v1.ComponentUnion{
Container: &v1.ContainerComponent{
Container: v1.Container{
Image: "image1",
},
},
},
})
// To add a new component to the devfile object
err := devfile.Data.AddComponents([]v1.Component{
{
Name: "component2",
ComponentUnion: v1.ComponentUnion{
Container: &v1.ContainerComponent{
Container: v1.Container{
Image: "image2",
},
},
},
},
})
// To delete a component from the devfile object
err := devfile.Data.DeleteComponent(componentName)
----
====

* Write a devfile by running:

====
----
// If the devfile object has been created with the devfile path already set, can simply call WriteYamlDevfile to write the devfile
err := devfile.WriteYamlDevfile()
// To write to a devfile from scratch
// create a new DevfileData with a specific devfile version
devfileData, err := data.NewDevfileData(devfileVersion)
// set schema version
devfileData.SetSchemaVersion(devfileVersion)
// To add devfile content, use library APIs
devfileData.AddComponents([]v1.Component{...})
devfileData.AddCommands([]v1.Commands{...})
......
// create a new DevfileCtx
ctx := devfileCtx.NewDevfileCtx(devfilePath)
err = ctx.SetAbsPath()
// create devfile object with the new DevfileCtx and DevfileData
devfile := parser.DevfileObj{
Ctx: ctx,
Data: devfileData,
}
// write to the devfile on disk
err = devfile.WriteYamlDevfile()
----
====