Resources

This section will take you through the process of creating a new v2 resource definition.

Prerequisites

• Good knowledge about the resource you're planning to implement
• Golang SDK: https://go.dev
• Understanding of our philosophy

Optional

• A clear picture of what you want to implement and how go generalize it

General information

When creating a new resource, editing, or deleting an existing resource for ROR the generator MUST be ran, this is required for amongst other things to update the TypeScript types.

Getting started

Cloning the repository

To start with you need to first setup your repositories ready for development. For how to do that please see here

Creating the base resource files

Create the resource definition

1. Creating it at:

ror/pkg/rorresources/rortypes

with the format:

resourcedef_<resourceName>.go

1. When creating this file the following rule must be followed:
   • The package name is rortypes
   • The structs all begin with Resource resulting your type to be Resource<YourResourceName>
   • Your main struct should contain a Spec and a Status field
   • The Spec is the desired state, while Status is observed state, more about that further down.

An example of a resourcedef:

package rortypes

type ResourceVirtualMachine struct {
        Id     string                       `json:"id"`
        Name   string                       `json:"name"`
        Spec   ResourceVirtualMachineSpec   `json:"spec"`
        Status ResourceVirtualMachineStatus `json:"status"`
}

type ResourceVirtualMachineSpec struct {
        Cpu             ResourceVirtualMachineCpuSpec             `json:"cpu"`
        Tags            []ResourceVirtualMachineTagSpec           `json:"tags"`
        Disks           []ResourceVirtualMachineDiskSpec          `json:"disks"`
        Memory          ResourceVirtualMachineMemorySpec          `json:"memory"`
        Networks        []ResourceVirtualMachineNetworkSpec       `json:"networks"`
        OperatingSystem ResourceVirtualMachineOperatingSystemSpec `json:"operatingSystem"`
}

type ResourceVirtualMachineStatus struct {
        Cpu             ResourceVirtualMachineCpuStatus             `json:"cpu"`
        Disks           []ResourceVirtualMachineDiskStatus          `json:"disks"`
        Memory          ResourceVirtualMachineMemoryStatus          `json:"memory"`
        Networks        []ResourceVirtualMachineNetworkStatus       `json:"networks"`
        OperatingSystem ResourceVirtualMachineOperatingSystemStatus `json:"operatingSystem"`
}
.
.
.

Note that JSON tags have to be in camel case, as the generator converts the Go structs to TypeScript, which does not support field names with hyphens.

Spec

Spec will be what we desire the configuration to be for when we wish to change something, like cpu, disk, or memory for the example above. Any parameter within here it is expected we're allowed to change if change from ROR is implemented.

If the resource is read-only, the Spec field is not necessary to implement.

Status

Status will be what we observe about this resource, like ids, the current cpu, disk, or memory for the example above.

Create the resource_input_filter definition

The resource_input_filter runs on import on that type, it can be used to censor, anonymize, remove, or change data before import.

While it has to be defined on every type, generally we create it and return nil for no action.

1. Create it at:

ror/pkg/rorresources/rortypes

with the format:

resouce_input_filter<resourceName>.go

1. Which should contain something to this example with swapped out with your core struct:

package rortypes

// (r *<ResourceName>) ApplyInputFilter Applies the input filter to the resource
func (r *<ResourceName>) ApplyInputFilter(cr *CommonResource) error {
        return nil
}

ROR definitions

1. Go to:

ror/pkg/rorresources/rordefs

1. And edit defs.go
2. On the top const definition, add your new agent in the format:

ApiResoureType<Name> ApiReesourceType = "<AgentName>"

1. And at the near bottom at at to the Resroucedefs slice:

{
        TypeMeta: metav1.TypeMeta{
                Kind:       "<Name",
                APIVersion: "<Version of your choice>",
        },
        Plural:     "<Plural of name>",
        Namespaced: false,
        Types:      []ApiResourceType{<Type>},
},

an example of a resource definition:

{
    TypeMeta: metav1.TypeMeta{
        Kind:       "VirtualMachine",
        APIVersion: "general.ror.internal/v1alpha1",
    },
    Plural:     "VirtualMachines",
    Namespaced: false,
    Types:      []ApiResourceType{ApiResourceTypeVmAgent},
    Versions:   []ApiVersions{ApiVersionV1, ApiVersionV2},
}

TypeMeta

TypeMeta is a standard Kubernetes API metadata struct that specifies the resource Kind and APIVersion. In this context it identifies what type of resource this definition represents and which API group/version it belongs to.

Plural

Used to generate functions that fetch multiple resources of a kind

Namespaced

TODO

Types

TODO

Versions

Used by the generator to fetch resource definitions of a specific version. Best practice is to set this to the highest version, unless you specifically need to support a lower version for some reason.