Add an example of the API's DynamicIdentityFileCreds (#42495)

api/client/client.go

@@ -604,6 +604,8 @@ func (c *Client) waitForConnectionReady(ctx context.Context) error {
 // Config contains configuration of the client
 type Config struct {
 	// Addrs is a list of teleport auth/proxy server addresses to dial.
+	// If you are using identity file credentials, at least one address must be supplied.
+	// This field is optional if you are using tsh profile credentials.
 	Addrs []string
 	// Credentials are a list of credentials to use when attempting
 	// to connect to the server.

api/client/credentials.go

@@ -380,6 +380,9 @@ func configureTLS(c *tls.Config) *tls.Config {
 // source of authentication for Client. It does not automatically watch the
 // identity file or reload on an interval, this is left as an exercise for the
 // consumer.
+//
+// DynamicIdentityFileCreds is the recommended [Credentials] implementation for
+// tools that use Machine ID certificates.
 type DynamicIdentityFileCreds struct {
 	// mu protects the fields that may change if the underlying identity file
 	// is reloaded.

api/client/credentials_test.go

@@ -17,24 +17,28 @@ limitations under the License.
 package client
 
 import (
+	"context"
 	"crypto/rand"
 	"crypto/rsa"
 	"crypto/tls"
 	"crypto/x509"
 	"crypto/x509/pkix"
 	"encoding/pem"
+	"log"
 	"math/big"
 	"os"
 	"path"
 	"path/filepath"
 	"testing"
+	"time"
 
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
 	"github.com/stretchr/testify/require"
 	"golang.org/x/crypto/ssh"
 
 	"github.com/gravitational/teleport/api/constants"
+	"github.com/gravitational/teleport/api/defaults"
 	"github.com/gravitational/teleport/api/identityfile"
 	"github.com/gravitational/teleport/api/profile"
 	"github.com/gravitational/teleport/api/utils/keys"
@@ -467,5 +471,44 @@ func TestDynamicIdentityFileCreds(t *testing.T) {
 	wantTLSCert, err = tls.X509KeyPair(secondTLSCertPem, keyPEM)
 	require.NoError(t, err)
 	require.Equal(t, wantTLSCert, *gotTLSCert)
+}
+
+func ExampleDynamicIdentityFileCreds() {
+	// load credentials from identity files on disk
+	cred, err := NewDynamicIdentityFileCreds("./identity")
+	if err != nil {
+		log.Fatal(err)
+	}
 
+	// periodically reload credentials from disk
+	go func() {
+		for {
+			log.Println("reloading credentials")
+			if err := cred.Reload(); err != nil {
+				log.Fatal(err)
+			}
+			log.Println("reloaded credentials")
+			time.Sleep(5 * time.Minute)
+		}
+	}()
+
+	ctx := context.Background()
+	clt, err := New(ctx, Config{
+		Addrs:       []string{"leaf.tele.ottr.sh:443"},
+		Credentials: []Credentials{cred},
+	})
+	if err != nil {
+		panic(err)
+	}
+
+	for {
+		log.Println("Fetching nodes")
+		_, err := clt.GetNodes(ctx, defaults.Namespace)
+		if err != nil {
+			log.Printf("ERROR Fetching nodes: %v", err)
+		} else {
+			log.Println("Fetching nodes: OK")
+		}
+		time.Sleep(1 * time.Second)
+	}
 }

docs/pages/api/architecture.mdx

@@ -58,17 +58,21 @@ and data generated by [Teleport CLIs](../reference/cli.mdx).
 Since there are several Credential loaders to choose from with distinct
 benefits, here's a quick breakdown:
 
- - Profile Credentials are the easiest to get started with. All you have to do
+ - Profile credentials are the easiest to get started with. All you have to do
    is log in to your device with `tsh login`. Your Teleport proxy address and
    credentials will automatically be located and used.
- - IdentityFile Credentials are the most well-rounded in terms of usability,
+ - Identity File credentials are the most well-rounded in terms of usability,
    functionality, and customizability. Identity files can be generated through
    `tsh login`, `tctl auth sign`, or with
    [Machine ID](../machine-id/introduction.mdx).
- - Key Pair Credentials have a much simpler implementation than the first two
+ - Dynamic Identity File credentials are Identity File credentials with support for
+   reloading credentials from disk. This makes them appropriate for Machine ID
+   integrations, as you can reload the credentials when Machine ID rotates the
+   underlying identity files.
+ - Key pair credentials have a much simpler implementation than the other
    Credentials listed and may feel more familiar. These are good for
    authenticating clients hosted directly on the auth server.
- - TLS Credentials leave everything up to the client user. This is mostly used
+ - TLS credentials leave everything up to the client user. This is mostly used
    internally, but some advanced users may find it useful.
 
 Here are some more specific details to differentiate them by: