yc

README

ydb-go-yc

Helpers to connect to YDB inside yandex-cloud.

Table of contents

1. Overview
2. About semantic versioning
3. Prerequisites
4. Installation
5. Usage

Overview

Currently package provides helpers to connect to YDB inside yandex-cloud.

About semantic versioning

We follow the SemVer 2.0.0. In particular, we provide backward compatibility in the MAJOR releases. New features without loss of backward compatibility appear on the MINOR release. In the minor version, the patch number starts from 0. Bug fixes and internal changes are released with the third digit (PATCH) in the version.

There are, however, some changes with the loss of backward compatibility that we consider to be MINOR:

• extension or modification of internal ydb-go-yc interfaces. We understand that this will break the compatibility of custom implementations of the ydb-go-yc internal interfaces. But we believe that the internal interfaces of ydb-go-yc are implemented well enough that they do not require custom implementation. We are working to ensure that all internal interfaces have limited access only inside ydb-go-yc.
• major changes to (including removal of) the public interfaces and types that have been previously exported by ydb-go-yc. We understand that these changes will break the backward compatibility of early adopters of these interfaces. However, these changes are generally coordinated with early adopters and have the concise interfacing with ydb-go-yc as a goal.

Internal interfaces outside from internal directory are marked with comment such as

// Warning: only for internal usage inside ydb-go-yc

We publish the planned breaking MAJOR changes:

• via the comment Deprecated in the code indicating what should be used instead
• through the file NEXT_MAJOR_RELEASE.md

Prerequisites

Requires Go 1.13 or later.

Installation

go get -u github.com/ydb-platform/ydb-go-yc

Usage

import (
    yc "github.com/ydb-platform/ydb-go-yc"
)
...
    db, err := ydb.Open(
        ctx,
        os.Getenv("YDB_CONNECTION_STRING"),
        yc.WithInternalCA(),
        yc.WithServiceAccountKeyFileCredentials("~/.ydb/sa.json"), // auth from service account key file
        //yc.WithMetadataCredentials(ctx), // auth inside cloud (virual machine or yandex function)
    )
    

Documentation

Index

• func NewClient(opts ...ClientOption) (credentials.Credentials, error)
• func NewInstanceServiceAccount(opts ...yc.InstanceServiceAccountCredentialsOption) *yc.InstanceServiceAccountCredentials
• func NewInstanceServiceAccountURL(url string) *yc.InstanceServiceAccountCredentials
• func WithAuthClientCredentials(opts ...ClientOption) ydb.Option
• func WithInternalCA() ydb.Option
• func WithMetadataCredentials(opts ...yc.InstanceServiceAccountCredentialsOption) ydb.Option
• func WithMetadataCredentialsURL(url string) ydb.Option
• func WithServiceAccountKeyCredentials(serviceAccountKey string, opts ...ClientOption) ydb.Option
• func WithServiceAccountKeyFileCredentials(serviceAccountKeyFile string, opts ...ClientOption) ydb.Option
• type ClientOption
  • func WithAudience(audience string) ClientOption
  • func WithCertPool(certPool *x509.CertPool) ClientOption
  • func WithCertPoolFile(caFile string) ClientOption
  • func WithDefaultEndpoint() ClientOption
  • func WithEndpoint(endpoint string) ClientOption
  • func WithFallbackCredentials(fallback credentials.Credentials) ClientOption
  • func WithInsecureSkipVerify(insecure bool) ClientOption
  • func WithIssuer(issuer string) ClientOption
  • func WithKeyID(keyID string) ClientOption
  • func WithPrivateKey(key *rsa.PrivateKey) ClientOption
  • func WithPrivateKeyFile(path string) ClientOption
  • func WithServiceFile(path string) ClientOption
  • func WithServiceKey(json string) ClientOption
  • func WithSourceInfo(sourceInfo string) ClientOption
  • func WithSystemCertPool() ClientOption
  • func WithTokenTTL(tokenTTL time.Duration) ClientOption

Functions

func NewClient

func NewClient(opts ...ClientOption) (credentials.Credentials, error)

func NewInstanceServiceAccount

func NewInstanceServiceAccount(
	opts ...yc.InstanceServiceAccountCredentialsOption,
) *yc.InstanceServiceAccountCredentials

func NewInstanceServiceAccountURL

func NewInstanceServiceAccountURL(url string) *yc.InstanceServiceAccountCredentials

func WithAuthClientCredentials

func WithAuthClientCredentials(opts ...ClientOption) ydb.Option

func WithInternalCA

func WithInternalCA() ydb.Option

WithInternalCA append internal yandex-cloud certs

func WithMetadataCredentials

func WithMetadataCredentials(opts ...yc.InstanceServiceAccountCredentialsOption) ydb.Option

func WithMetadataCredentialsURL

func WithMetadataCredentialsURL(url string) ydb.Option

func WithServiceAccountKeyCredentials

func WithServiceAccountKeyCredentials(serviceAccountKey string, opts ...ClientOption) ydb.Option

func WithServiceAccountKeyFileCredentials

func WithServiceAccountKeyFileCredentials(serviceAccountKeyFile string, opts ...ClientOption) ydb.Option

Types

type ClientOption

type ClientOption = auth.ClientOption

func WithAudience

func WithAudience(audience string) ClientOption

WithAudience set provided audience.

func WithCertPool

func WithCertPool(certPool *x509.CertPool) ClientOption

WithCertPool set provided certPool.

func WithCertPoolFile

func WithCertPoolFile(caFile string) ClientOption

WithCertPoolFile try set root certPool from provided cert file path.

func WithDefaultEndpoint

func WithDefaultEndpoint() ClientOption

WithDefaultEndpoint set endpoint with default value.

func WithEndpoint

func WithEndpoint(endpoint string) ClientOption

WithEndpoint set provided endpoint.

func WithFallbackCredentials

func WithFallbackCredentials(fallback credentials.Credentials) ClientOption

WithFallbackCredentials makes fallback credentials if primary credentials are failed

func WithInsecureSkipVerify

func WithInsecureSkipVerify(insecure bool) ClientOption

WithInsecureSkipVerify set insecureSkipVerify to true which force client accepts any TLS certificate presented by the iam server and any host name in that certificate.

If insecureSkipVerify is set, then certPool field is not used.

This should be used only for testing purposes.

func WithIssuer

func WithIssuer(issuer string) ClientOption

WithIssuer set provided issuer.

func WithKeyID

func WithKeyID(keyID string) ClientOption

WithKeyID set provided keyID.

func WithPrivateKey

func WithPrivateKey(key *rsa.PrivateKey) ClientOption

WithPrivateKey set provided private key.

func WithPrivateKeyFile

func WithPrivateKeyFile(path string) ClientOption

WithPrivateKeyFile try set key from provided private key file path

func WithServiceFile

func WithServiceFile(path string) ClientOption

WithServiceFile try set key, keyID, issuer from provided service account file path.

Do not mix this option with WithKeyID, WithIssuer and key options (WithPrivateKey, WithPrivateKeyFile, etc).

func WithServiceKey

func WithServiceKey(json string) ClientOption

WithServiceKey try set key, keyID, issuer from provided service account key.

Do not mix this option with WithKeyID, WithIssuer and key options (WithPrivateKey, WithPrivateKeyFile, etc).

func WithSourceInfo

func WithSourceInfo(sourceInfo string) ClientOption

WithSourceInfo set sourceInfo

func WithSystemCertPool

func WithSystemCertPool() ClientOption

WithSystemCertPool try set certPool with system root certificates.

func WithTokenTTL

func WithTokenTTL(tokenTTL time.Duration) ClientOption

WithTokenTTL set provided tokenTTL duration.