Golang client library

[andrewbaxter]

I've been poking around at building Talos functionality into internal commands/scripts. I see there's a go client at github.com/siderolabs/talos/pkg/machinery/client. Is that intended for general consumption, or is there a better client available?

One thing I was trying to do was get a list of cluster member ips, i.e. talosctl get members. AFAICT the way to do that is:

• Set up client
• Get resource kind with namespace "", type "members"
• Do this COSI.List thing
• Go through the resource kind display columns to find ADDRESS
• Get the json path from that
• Convert the item into protobuf.Resource to get access to the yaml
• Marshal item.Spec() into yaml since it's protobuf.protoSpec which is a private type Get the yaml via Marshal() then .Spec.YamlSpec
• Unmarshal item.Spec() from yaml into any
• Get the field using the json path
• Do further type casting/unmarshaling to actually get the list of addresses

It's not very type safe, there are lots of parameters that I don't really know about or shouldn't have to worry about (resource.VersionUndefined) in default operation. This is roughly what talosctl get members appears to do.

I'd have expected something like

members, err := talosClient.GetMembers()
if err != nil { return err }
for _, member := range members {
    log.Printf("Member with ip %s", member.Addresses[0])
}

Are the json paths stable in the api? It'd be a bit simpler if I could hard code a jsonpath and skip the kind display columns search stuff...

[smira]

You don't need to do any type casting or anything like that.

Once you set up a client, you can do something close to:

talos/internal/integration/api/discovery.go

Lines 336 to 359 in 8b64f68

	items, err := safe.StateListAll[*cluster.Member](nodeCtx, suite.Client.COSI)
	suite.Require().NoError(err)
	return safe.ToSlice(items, func(m *cluster.Member) *cluster.Member { return m })
	}
	func (suite *DiscoverySuite) getNodeIdentity(nodeCtx context.Context) *cluster.Identity {
	identity, err := safe.StateGet[*cluster.Identity](nodeCtx, suite.Client.COSI, resource.NewMetadata(cluster.NamespaceName, cluster.IdentityType, cluster.LocalIdentity, resource.VersionUndefined))
	suite.Require().NoError(err)
	return identity
	}
	func (suite *DiscoverySuite) getAffiliates(nodeCtx context.Context, namespace resource.Namespace) []*cluster.Affiliate {
	var result []*cluster.Affiliate
	items, err := safe.StateList[*cluster.Affiliate](nodeCtx, suite.Client.COSI, resource.NewMetadata(namespace, cluster.AffiliateType, "", resource.VersionUndefined))
	suite.Require().NoError(err)
	items.ForEach(func(item *cluster.Affiliate) { result = append(result, item) })
	return result
	}

This gives you completely typed resources back.

[andrewbaxter]

Oh awesome, I'll try that out!

So, reading between the lines, would it be correct to say that the Talos API is built on COSI and users are expected to interface primarily with COSI? I.e. it's not a standalone Talos API client, but essentially extensions to use with a COSI client library? Is there some documentation on this (the Go Talos client, or maybe also a practical guide to consuming COSI in Go)?

Out of curiosity, is there a reason talosctl itself doesn't use safe?

[smira]

Part of Talos API is COSI API which allows you to list/get/watch resources. Talos API client exposes COSI client for you as well, so you can simply use any COSI methods on it (but keep in mind, Talos resource API is read-only).

Talos API has some other APIs which are not COSI based, e.g. Reboot() API.

Out of curiosity, is there a reason talosctl itself doesn't use safe?

It does in some places, but get command allows you to see any resource, so it doesn't make any sense to use safe. Moreover, talosctl can even show resources it doesn't know about (e.g. you can use older talosctl with newer Talos sometimes).

[andrewbaxter]

Ah okay, that makes a lot of sense. Thanks again!