2022-04-06

Pulumi を C# で書くときに気を付けていること

Pulumi C#

Pulumi は複数の言語で書くことができるのですが、そのうちの1つに .NET (C#) もあります。

以前 Pulumi を C# で書く時の事始めシリーズを書いていましたが、あれから時間がたって書き方も変わりました。今回は、実際にどのように書くことで Pulumi で書きやすい、IaC制御しやすいを目指しているのかを言語化します。

tl;dr;
コンストラクタで処理を完結させる
Output`T型で将来の値を表現する
- 非同期メソッドと Output`T
- Output`T の T を取り出したい
リソースインスタンス作成はコンポーネントの責務を徹底する
- リソース処理の前に値の検証をする
- コンポーネント外部へのプロパティの公開
定数クラスと分岐で環境差分を表現する
- 環境差分と定数クラス
- 環境ごとのリソースの違いはコンポーネントで頑張る
まとめ

tl;dr;

Pulumi + C# の時に、Pulumi の考えているやりやすいにのっかりつつ、C# 的に書きやすく、IaC として管理しやすいかを検討します。ポイントは4点です。

コンストラクタで処理を完結させる
Output`T型で将来の値を表現する
リソースインスタンス作成はコンポーネントの責務を徹底する
定数クラスと分岐で環境差分を表現する

DO/DO NOT/CONSIDER で気を付けていることを順にあげていきます。

コンストラクタで処理を完結させる

✔️ DO: コンストラクタで処理を行う
❌ DO NOT: Task メソッドに処理を分けて呼び出すことを避ける

AWS CDK も似た感じですが、リソース/コンポーネントの作成処理はコンストラクタで完結させます。例えば次のようになります。

// DO
return await Deployment.RunAsync<MyStack>();

class MyStack : Stack
{
    public MyStack()
    {
        var foo = new FooResource("Foo",  new FooArgs
        {
            // 何か処理
        });
    }
}

Task ExecuteAsync() のように非同期メソッドを生やして呼び出す、ということは避けるといいでしょう。非同期メソッドに処理を分けると、そのメソッド内部では async/await を使えますが、呼び出し元の最上流はコンストラクタです。コンストラクタ呼び出し時点でリソースが作られないのは良しとしても、ExecuteAsync 呼び出し忘れや、Task<T>.GetAwaiter().GetResult() とか絶対避けたいでしょう。あと、明らかに冗長です。

// DO NOT
return await Deployment.RunAsync<MyStack>();

class MyStack : Stack
{
    public MyStack()
    {
        var foo = new FooComponent();
        foo.ExecuteAsync().GetAwaiter().GetResult(); // したくない
    }
}

public class FooComponent : ComponentResource
{
    public FooComponent() : base()
    {
        // 初期化
    }

    public async Task ExecuteAsync()
    {
        var foo = new FooResource("Foo",  new FooArgs
        {
            // 何か処理
        });
    }
}

コンストラクタで async/await は使えないので非同期処理をどうするのか、という疑問がわきますが、それは次の Output<T> を使う話になります。

Output`T型で将来の値を表現する

Pulumi で何かしらのリソースを作成するときに、リソースが作成されないと決定できない「将来の値 = (いわゆるPromise)」は Output<T> 型で表現されます。

www.pulumi.com

✔️ DO: 将来の値は Output<T> を伝搬させる
✔️ DO: Taskを扱う非同期処理は Output<T> でくるむ
❌ DO NOT: await して生の値をとろうとしない
✔️ DO: Output<T> の生の値 Tが必要な場合は Output<T>.Apply() メソッド内部のラムダで利用する

Pulumi を C# で書くときは、Output<T> で将来の値を伝搬するのを徹底するのがよいでしょう。例えば Output<T> を活用すると、次のように foo リソースが作成されていなくても bar リソースで fooリソースを使う/依存があることを示すことができます。

// DO
return await Deployment.RunAsync<MyStack>();

class MyStack : Stack
{
    public MyStack()
    {
        var foo = new FooResource("Foo",  new FooArgs
        {
            // 何か処理
        });

        var bar = new BarResource("Bar", new BarArgs
        {
            FooId = foo.Arn, // foo が生成されるまで値が未確定。fooへの依存も自動的に解析される。
        });
    }
}

Output<T> に対応する、リソースが受け入れるときの型が Input<T> ですが、自分で利用する機会はほぼなく Output<T> しか使わないでしょう。

非同期メソッドと Output`T

Pulumi には、現在認証しているクラウド環境やその環境のリソースを取得するメソッドが用意されています。例えば、AWS 環境で既存の Vpc を取得するメソッドがあります。

// メソッドの返り値は、Task<Pulumi.Aws.Ec2.GetVocResult>
Pulumi.Aws.Ec2.GetVpc.InvokeAsync(new Pulumi.Aws.Ec2.GetVpcArgs { Id = "foo" });

C# 的には Task なんだから await することで待ちたくなりますが、それでは前出のasync/await を書こうとしたときのジレンマに陥ります。 Taskを扱う非同期処理は、await する代わりに Output<T> でくるんであげることで自然と扱えます。

先の例を Output<T> でくるむには、Output.Create<T>() メソッドを利用するといいでしょう。

// DO
var vpcId = Output.Create(Pulumi.Aws.Ec2.GetVpc.InvokeAsync(new Pulumi.Aws.Ec2.GetVpcArgs { Id = "vpc-0123456" }));

// DO NOT
var vpcId = await Pulumi.Aws.Ec2.GetVpc.InvokeAsync(new Pulumi.Aws.Ec2.GetVpcArgs { Id = "vpc-0123456" });

Output`T の T を取り出したい

また、リソースを生成した結果の Output<T> を先ほどのInvokeAsync 内の処理で使いたいことがあります。

var foo = new FooResource("Foo",  new FooArgs
{
    // 何か処理
});

// プロパティは仮です、実際とは異なります。
Pulumi.Aws.Iam.GetPolicyDocument.InvokeAsync(new GetPolicyDocumentArgs
{
    Resources = new [] { /* ここでfooリソースのArnを使いたい*/ }
});

直接 foo.Arn を指定しようとすると foo.Arn は Output<T> なので文字列には変換されません。(ここが CDK との違いですね)

Output<T> の T を直接使用した処理を書きたい場合は、Output<T>.Apply<a>()メソッドのラムダ内部で処理を書くといいでしょう。 Output<T>.Apply<a>() の返り値は Output<a> となるので、結果を他リソースに食わせる時も自然と与えることができます。

// DO
var policy = foo.Arn.Apply(arn => Pulumi.Aws.Iam.GetPolicyDocument.InvokeAsync(new GetPolicyDocumentArgs
{
    Resources = new [] { $"{arn}/*" } // T が入っている
}));

// DO NOT
var policy = Output.Create(Pulumi.Aws.Iam.GetPolicyDocument.InvokeAsync(new GetPolicyDocumentArgs
{
    Resources = new [] { $"{foo.Arn}/*" } // Output<T> のままなのでダメ
}));

Output<T> から別の Output<T> に変換したいときも同じように Output<T>.Apply() や Output<T>.Format() が利用できます。

// 出力される Output<string> は arn:aws:s3:::foo に変換される。
Output.Create("foo").Apply(x => $"arn:aws:s3:::{x}");

リソースインスタンス作成はコンポーネントの責務を徹底する

✔️ DO: 実装 (リソース) はコンポーネントに管理させる
❌ DO NOT: Stack に直接実装 (リソース) を記述する
✔️ CONSIDER: リソース処理の前に値の検証をする
✔️ DO: 他のコンポーネントからリソースの結果を使用たいときはプロパティを公開する

Pulumi でリソースを作る = リソースインスタンスを作ることを指します。また、リソースは1つ一つがユニークな urnで識別され、urn はリソースがコンポーネントに含まれるかどうかでも IDが変わります。このため、リソースは当初からコンポーネントに分離することを念頭において、 Stack に直接書き出すのは避けるといいでしょう。

// DO
class MyStack : Stack
{
    public MyStack()
    {
        var opts = new ComponentResourceOptions { Parent = this };

        // コンポーネントを呼び出す
        var sg = new SecurityGroupComponent("my-sg", "securitygroup", opts, new SecurityGroupComponentArgs
        {
            VpcId = "vpc-0123456",
        });
    }
}

public class SecurityGroupComponent : ComponentResource
{
    public SecurityGroupComponent(string service, string component, ComponentResourceoptions opts, SecurityGroupComponentArgs args): base($"{service}:components:{component}", $"{service}-{component}", opts)
    {
        var opt = new CustomResourceOptions { Parent = this };

        // リソースインスタンス管理はコンポーネントのお仕事
        var egresss = new SecurityGroupEgressArgs
        {
            FromPort = 0,
            ToPort = 0,
            Protocol = "-1",
            CidrBlocks = new[] { "0.0.0.0/0" },
        };

        var aSg = new SecurityGroup("a-sg", new SecurityGroupArgs
        {
            Description = "a-SG"
            VpcId = args.VpcId
            Ingress = new[] {
                new SerurityGroupIngressArgs
                {
                    FromPort = 80,
                    ToPort = 80,
                    Protocol = "TCP",
                    Descrsiption = "HTTP access from XXXX",
                    CidrBlocks = "0.0.0.0/0",
                }
                new SerurityGroupIngressArgs
                {
                    FromPort = 443,
                    ToPort = 443,
                    Protocol = "TCP",
                    Descrsiption = "HTTPS access from XXXX",
                    CidrBlocks = "0.0.0.0/0",
                }
            },
            Egress = new[] { egress },
        }, opt);

        var bSg = new SecurityGroup("b-sg", new SecurityGroupArgs
        {
            Description = "b-SG"
            VpcId = args.VpcId
            Ingress = new[] {
                new SerurityGroupIngressArgs
                {
                    FromPort = 0,
                    ToPort = 0,
                    Protocol = "-1",
                    Descrsiption = aSg.Name,
                    SecurityGroups = aSg.Id,
                    Self = false,
                }
            },
            Egress = new[] { egress },
        }, opt);
    }
}

次のようにリソースを Stack に直接書き出したが最後、そのリソースの管理は誰がやるのか困り始めることでしょう。

// DO NOT
class MyStack : Stack
{
    public MyStack()
    {
        var opt = new CustomResourceOptions { Parent = this };

        // リソースを直接Stackに書き出す
        var egresss = new SecurityGroupEgressArgs
        {
            FromPort = 0,
            ToPort = 0,
            Protocol = "-1",
            CidrBlocks = new[] { "0.0.0.0/0" },
        };

        var aSg = new SecurityGroup("a-sg", new SecurityGroupArgs
        {
            Description = "a-SG"
            VpcId = args.VpcId
            Ingress = new[] {
                new SerurityGroupIngressArgs
                {
                    FromPort = 80,
                    ToPort = 80,
                    Protocol = "TCP",
                    Descrsiption = "HTTP access from XXXX",
                    CidrBlocks = "0.0.0.0/0",
                }
                new SerurityGroupIngressArgs
                {
                    FromPort = 443,
                    ToPort = 443,
                    Protocol = "TCP",
                    Descrsiption = "HTTPS access from XXXX",
                    CidrBlocks = "0.0.0.0/0",
                }
            },
            Egress = new[] { egress },
        }, opt);
    }
}

コンポーネントでリソースインスタンスを作成するので、リソース作成に必要な値をコンポーネントに渡す必要があります。適当なrecord クラスで渡してあげると簡単でいいでしょう。

// DO
class MyStack : Stack
{
    public MyStack()
    {
        var opts = new ComponentResourceOptions { Parent = this };

        // コンポーネントを呼び出す
        var sg = new SecurityGroupComponent("my-sg", "securitygroup", opts, new SecurityGroupCompoonentArgs
        {
            VpcId = "vpc-0123456",
        });
    }
}

public class SecurityGroupComponent : ComponentResource
{
    public SecurityGroupComponent(string service, string component, ComponentResourceoptions opts, SecurityGroupComponentArgs args): base($"{service}:components:{component}", $"{service}-{component}", opts)
    {
        // 省略
    }
}

public record SecurityGroupComponentArgs
{
    public Output<string> VpcId { get; init; }
}

リソース処理の前に値の検証をする

各種ComponentArgs には、値の検証を担保させると Component内部での入力値の検査のほとんどを考慮しなくてよくなるのでオススメです。

// CONSIDER
public class SecurityGroupComponent : ComponentResource
{
    public SecurityGroupComponent(string service, string component, ComponentResourceoptions opts, SecurityGroupComponentArgs args): base($"{service}:components:{component}", $"{service}-{component}", opts)
    {
        // 初めに検証する
        args.Validate();

        // 省略
    }
}

public interface IValidate
{
    void Validate();
}

public record SecurityGroupComponentArgs : IValidate
{
    public Output<string>? VpcId { get; init; }

    [MemberNotNull(nameof(VpcId))]
    public void Validate()
    {
        if (VpcId is null) throw new ArgumentOutOfRangeException(nameof(VpcId));
    }
}

もちろんVpcId のように必須なものはコンストラクタでもいいでしょう。

// CONSIDER
public record SecurityGroupComponentArgs(Output<string> VpcId) : IValidate
{
    public IReadOnlyList<string>? Nanika { get; init; }

    [MemberNotNull(nameof(Nanika))]
    public void Validate()
    {
        if (Nanika is null) throw new ArgumentOutOfRangeException(nameof(Nanika));
    }
}

コンポーネント外部へのプロパティの公開

C# ではクラスの内部の情報を公開するときにプロパティを使いますが、Pulumi でもそれは変わりません。公開したいリソースは get only プロパティを使うといいでしょう。

Pulumi コンソールでStack 出力に表示したい場合は、[Output] 属性を付けたプロパティで公開します。プリミティブな型でないと表示できないので注意です。

// DO
class MyStack : Stack
{
    public MyStack()
    {
        var opts = new ComponentResourceOptions { Parent = this };

        var sg = new SecurityGroupComponent("my-sg", "securitygroup", opts, new SecurityGroupComponentArgs
        {
            VpcId = "vpc-0123456",
        });

        SecurityGroupAId = sg.A.Id
    }

    // Stack の Output に公開
    [Output]
    public Output<string> SecurityGroupAId { get; set; } // set 必須
}

public class SecurityGroupComponent : ComponentResource
{
    // リソースを公開する
    public SecurityGroup A { get; }

    public SecurityGroupComponent(string service, string component, ComponentResourceoptions opts, SecurityGroupComponentArgs args): base($"{service}:components:{component}", $"{service}-{component}", opts)
    {
        var aSg = new SecurityGroup("a-sg", new SecurityGroupArgs
        {
            // 省略
        }

        A = aSg;
    }
}

定数クラスと分岐で環境差分を表現する

✔️ DO: 定数クラスに環境ごとの値を定義して Stack で参照させる
❌ DO NOT: Stack に環境ごとの値を直接書く
✔️ CONSIDER: 環境ごとのリソースの違いはコンポーネントの分岐などで表現する

環境差分と定数クラス

コンポーネントの処理は環境で同じ、コンポーネントに与える値だけ違うというケースが多いでしょう。この場合、コンポーネント呼び出し時にStackへ直接値を書くのではなく、定数クラスを用意して参照させると環境ごとの差分が管理しやすいのでオススメです。

// DO
public static class Constants
{
    public const string Project = "MyProject";
    public const string Env = "dev";
    public const string Service = Project + "-" + Env;

    public static class Vpc
    {
        VpcId = "vpc-0123456"; // 環境ごとに違うであろう値
    }
}

class MyStack : Stack
{
    public MyStack()
    {
        var opts = new ComponentResourceOptions { Parent = this };

        var sg = new SecurityGroupComponent("my-sg", "securitygroup", opts, new SecurityGroupComponentArgs
        {
            VpcId = Constants.Vpc.VpcId,
        });
    }
}

// DO NOT
class MyStack : Stack
{
    public MyStack()
    {
        var opts = new ComponentResourceOptions { Parent = this };

        var sg = new SecurityGroupComponent("my-sg", "securitygroup", opts, new SecurityGroupComponentArgs
        {
            VpcId = "vpc-0123456", // 直接値を指定するのは避けたい
        });
    }
}

環境ごとのリソースの違いはコンポーネントで頑張る

コンポーネントの処理は環境で同じ、コンポーネントに与える値だけ違うというケースが多いでしょう。

と書きましたが、そんなの絵空事です。実際には、開発にはあるけど、本番にはないリソースというのはよくある話でしょう。

こういった環境差分は、コンポーネントの中で分岐などで適当に頑張るといいでしょう。幸いにして Terraform と違ってこういった処理は圧倒的にやりやすいのでいい感じの方法をとればいいと思います。

// CONSIDER
public class SecurityGroupComponent : ComponentResource
{
    public SecurityGroupComponent(string service, string component, ComponentResourceoptions opts, SecurityGroupComponentArgs args): base($"{service}:components:{component}", $"{service}-{component}", opts)
    {
        args.Validate();

        if (args.EnableA)
        {
            // A の セキュリティグループを作る
        }
    }
}

public record SecurityGroupComponentArgs : IValidate
{
    public Output<string>? VpcId { get; init; }
    public bool EnableA { get; init; }

    [MemberNotNull(nameof(VpcId))]
    public void Validate()
    {
        if (VpcId is null) throw new ArgumentOutOfRangeException(nameof(VpcId));
    }
}

まとめ

つらつらと普段気を付けていることを挙げてみました。 C# に限らず、Pulumiは各種言語のやりやすいように書けばインフラが管理できるのはとても便利です。 Pulumi と Terraform を行き来していると、Terraform の言語機能の貧弱さに驚くとともに、今ある値かを意識することなくかけるのはすごいと感じます。

利用者の多さ、言語機能の小ささから今後もTerraform は広く使われるでしょうが、アプリケーションエンジニアの立場から見ると Pulumi は非常に扱いやすく設計も応用できるので好ましいと感じます。

Terrafom も Pulumi もよい、チームとしてより書きやすい、手になじむものを採用していけるといいですね。

2022-03-20

Pulumi で Stack解析中の例外でリソースが全て消えてしまうのを防ぐ

Pulumi C#

Pulumi は Stack の解析を行って、現在のステートとの差分でどのような処理をするか preview / up で表示します。このため、Stack の解析中 (=コードをビルドして実行してStack生成中) に例外が生じたときにどのようにハンドルされるかは重要です。

今回はユーザー側の誤った記述で、Stack解析に例外が起こっても処理が止まらず実行されたのをメモしておきます。

tl;dr;

sdk/dotnet を利用する場合、Program.Main の返り値の型は int または Task<int> にしましょう
Top-level statement なら return を忘れずに、return await Deployment.RunAsync<MyStack>(); としましょう

どういう問題なのか

C# でPulumi を記述する場合、多くの場合は Stack を継承した自分の定義を用いるでしょう。 pulumi preview や pulumi apply でStack を実行中に例外が発生した場合は、pulumi cli はそれを検知して実行を止めなくてはいけません。 pulumiは例外を検知すると、「何もStackの内容を実行せず」例外をターミナルに表示して終了します。

しかしProgram.Mainメソッドの返り値の型を int あるいは Task<int> にしていないと、例外が起こっても pulumi cli は実行を継続しようとします。この状態で例外が起こると、「例外以降のコードで記述されたリソースに削除マーカーを付与」して差分+例外をターミナルに表示して終了します。

// bad
public static async Task Main(string[] args)
{
    await Deployment.RunAsync<MyStack>();
}

// bad (Top-Level statement)
await Deployment.RunAsync<MyStack>();

Issue が作られておりそちらを見ると詳しくわかります。

github.com

対処方法は前述のとおり、Mainメソッドの返り値を int か Task<int> にしましょう。

// ok
public static async Task<int> Main(string[] args)
{
    return await Deployment.RunAsync<MyStack>();
}

// ok (Expression-bodied Method)
public static async Task<int> Main(string[] args) => await Deployment.RunAsync<MyStack>();

// ok (Top-Level statement)
await Deployment.RunAsync<MyStack>();

何がおこったのか

Pulumi は言語のビルドは pulumi cli と切り離されているので、何気に .NET 6 でもビルド、実行できたりします。その際にうかつにも、await Deployment.RunAsync<MyStack>(); と return を忘れて書いてしまったために、作成してあったリソースの多くが消えるという目にあったのでした。

// missing return!!
await Deployment.RunAsync<MyStack>();

Pulumi は GitHub Aapp あるいは GitHub Actions で PR で差分を表示できるのですが、GitHub Actions でコメントを書くのを使っていたために、差分が埋もれてしまい気づけなかったという顛末です。

対処は return をつけるだけです。誰かの役に立つと幸いです。

Pulumi に期待すること

例外起こったら Environment.ExitCode = -1 など適切な終了コードをセットしてほしいです。現在はそういったことをしていないのを、終了コードを Main メソッドで示さないと死ぬので基盤で対処してほしい...。

github.com

2021-12-31

2021年を振り返って

Review

毎年やっている昨年の振り返りをしてみます。2020年忘れてました。

2019年はこれ。

tech.guitarrapc.com

総合
経営
プログラミング
- CSharp
- IaC
- Kubernetes
記事
ライフスタイル
2022年は?

総合

2021年は、2020年にやったことをさらに深めていく年でした。 2019年からやっていることを深く広くしていくことが求められており、相変わらず毎日新しいことを学んでいます。クライアントにフルコミットが必要で、この自社の時間を設けるのが難しくて頭が痛い問題が解消しませんでした。

サービス基盤を全面的にみているのですが、基盤を安定させつつ、改善したり抜本的な変更をしていくことを継続的に行っています。省力で行うため2019年から IaC で100%管理を続けており、かなり有効なのでおすすめです。Kubernetes + IaC じゃないと手が足りなかったので選択は正解なのですが、相談できる仲間が足りないと感じていて2022年はかなり頭を痛めそうです。

2021年もわからないことへの挑戦の連続でしたが、教わったり助けてもらいつつ分からないことを1つずつ潰せもしました。来年以降の自分に投げつけた課題もありますが、今年一年みても、寝かせると問題が問題でなくなったり、問題への解決方法を見つけたりするので、優先順位をつけて寝かせるのは大事。

経営

2021年は、あとはリリースというところまで進めたプロダクトをリリースしない決定をしており、なかなかリリースできないというのを痛感しています。自社よりも他から請け負っている仕事に力が使われているのは、2020年より強くなっており反省しかない。

2022年は2021年の反省を生かさないといけない年になります。

プログラミング

C#、Golang、TypeScript がメインです。

CSharp

2021年、C# でインフラからサーバー、クライアントまで完結できるかと思って取り込んでいたのですができるものですね。インフラは Pulumi や aws-cdk を使うのですが、おおむね terraform でできることは Pulumi でカバーできます。

C# 10 が出て、C# はかなり手触りが良くなりました。 Minimal API と File scope namespace 、Implicit Global Namespace で本当に書くのが楽になりました。

IaC

Terraform と Pulumi をメインに使い、Bicep も使っています。 Azure で IaCをちゃんとやろうと思ったら、残念ながら Bicep は選んではいけないという学びが悲しかったです。

Pulumi は Pulumi Native が出たことで、Upstream である Terraform の対応が入らないと Pulumi の対応が入らないという悪循環が解消されつつあります。とはいえ Pulumi Native は Beta なだけあって Beta な品質で、特にステートとリソースの協調がまだまだ足りない感じです。(Tag が順不同で実行ごとに変更かかる、変更が安定して適用されないなどプロダクション品質ではない)

Terraform は 1.1 がかなりいい感じで、ようやく state mv が改善されました。このままよくなってほしいけど、Pulumi の State move はクソなのであっち方向にはいってほしくないところ。

dev.classmethod.jp

Terraform の CI/CD は、さんざん Terraform Cloud の VCS 連携を使っていましたが、API ベースでの連動に切り替えました。変なことできないという意味ではVCS連携がいいのですが、どうしても GitHub PR との連動が弱いので、バランスを見ると API ベースがいいですね。とくに tfcmt と github-comment の組み合わせはいい感じなので、おすすめできます。

Pulumi の CI/CD は GitHub Actions の v3 が出たのですが、安定して微妙な使い勝手です。Dockerベースの頃より格段にいいのですが、tfcmt のような楽な使い勝手じゃないのでなんとも微妙。

Kubernetes

Kubernetes と YAML の地獄、どうしようもないのだろうかと真剣に悩んでいます。 Kustomize や helm という問題ではなく、YAML を書くのがしんどい、とはいえ DSL 的に他から出すのもブラックボックスで嫌で詰んでる。

記事

17本、少な。あんまり言語的なのを書かなかったのですが、社内やお手伝い先でさんざん書いていてちょっとブログに起こすのがしんどかったりします。

書くことはあるけど、またこっちにも書くのかとなっているのがよくないので反省です。

ライフスタイル

コロナ大変です。 2021年10月から少し収まったので久々に外出しましたが、好きなところに行くのは楽しいものです。

家の中は、吊り収納にはまっています。水回りは徹底的に浮かしているので、掃除がほぼ不要になって最高です。

スタンディングデスクを使ったことでメリハリも効いてきたので、2022年はよりよく頑張っていきたいところ。

2022年は?

クライアントとの協業は年々強くなっています。期待に応えていきたいところ。そして自社のリリースも。

個人的にはC# + Kubernetes がどうなるか 2022年はカギになりそうです。

2021-12-07

dotnet format を CI で行って継続的にコードフォーマットしていく

この記事は Qiita C# Advent Calendar 2021 7日目の記事です。

Visual Studio や Rider でのコードフォーマットは個人で使うにとても良く、開発上は必須といえます。しかしチーム開発でコードフォーマットをいい感じに標準化させたい、労力かけずにフォーマット修正をかけたいと思ったときには CLI で実行できてほしいものです。

dotnet には長らく標準的なコードフォーマッタ用のCLI がありませんでしたが、.NET 6 SDK からコードフォーマッタ dotnet format が標準組み込みとなりました。

今回は C#で開発するにあたり、CI でCLIを実行してC# のコードフォーマットを自動修正する方法を紹介します。

普段からやっていると開発上でフォーマッタで困らなくなるので、塵も積もれば的な良さを感じる人がいれば幸いです。

tl;dr;
実行例
GitHub Actions のワークフロー全体像
dotnet format を使う基本
- ドキュメント
- .editorconfig を用意する
.NET 5 での dotnet format

tl;dr;

CI を使ってコードフォーマットをかけて変更をPR、レビューを通して自分たちのルールを見直したり、変更を取り込むという一連のフローができるようになります
GitHub Actions で例を示しますが、ほかのCI でも同様に実施ができます
コードフォーマットの対象 csproj やcsファイルを絞れるので、Unity など指定プロジェクトを除外することも可能です
週一程度の緩い利用からはじめて、ストレスにならない程度の運用から始めるといいでしょう

実行例

まずはGitHub Actionsを実行して作られたPRから見てください。

github.com

この記事で紹介するGitHub Actionsを使うと、dotnet format された結果がPRで上がってきます。 PR は Stats と Files と TargetProjects を示しています。ひと月あまり運用していて、ここが足りない、みたい、というフィードバックを受けてこのような形になりました。

Stats: パスごとの変更統計
Files: dotnet format がかかったファイル一覧 (場合によってファイル数が膨大になるので閉じています)
Target Projects: 対象の csproj 一覧

GitHub Actions のワークフロー全体像

先ほどのPR を作る GitHub Actions を示します。このGitHub Actions は src/dotnet にある sln に基づいて、C# プロジェクトを週一/手動でコードフォーマットします。

gist.github.com

プロジェクトが見たい場合は、元のリポジトリをどうぞ。

github.com

dotnet format のポイントは3つです。

dotnet format を使うには、.NET SDK 6 を setup-dotnet action でインストールします
dotnet format は sln や slnf に対して実行するのがおすすめ。個別の .cs や csproj でも実行はできますが制御しやすいでしょう
--exclude を使って、コードフォーマットの除外ファイルやcsprojを指定できます。複数除外もできます

GitHub Actions の中身を軽く説明します。

24行目: sln が含んでいる csproj を一覧で取得しています
34行目: PR駆動時などに、dotnet format の問題をGitHub 上で示します
38行目: ここで dotnet format をかけています
42行目～: 変更があったか、変更の統計などを取得しています
70行目: dotnet format で変更があった時だけ PR を作っています

dotnet format を使う基本

ドキュメント

.NET 6 の dotnet format は、Microsoft Docs で紹介されているので、まずは見てみるといいでしょう。オプションも一通り説明があります。

docs.microsoft.com

リポジトリを見ると使い方がすべて乗っています、おすすめ。

github.com

サブコマンドが3つありますが、気にせず dotnet format するのがおすすめです。何も考えず dotnet format をかけられる環境を維持しましょう。

dotnet format whitespace: fixes whitespace
dotnet format style: runs code style analyzers
dotnet format analyzers: runs third party analyzers

.editorconfig を用意する

dotnet format は .editorconfig をフォーマットルールにするので、まずこれを用意しましょう。

.editorconfig を sln と同じ階層に置いて、C# のフォーマットルールを .editorconfig に定義すれば準備完了です。(リポジトリルートに配置しても動作しますが把握が難しくなるので避けています)

例としたリポジトリで使っている .editorconfig は Roslynチームのをベースにしています。チームごとにルールがあると思うので参考程度に。

https://github.com/guitarrapc/githubactions-lab/blob/main/src/dotnet/.editorconfiggithub.com

.editorconfig 定義すると dotnet format だけじゃなく Visual Studio でも同じフォーマットルールが適用されます。dotnet format を使わなくても、チーム開発でコーディングルールを持っているところでは .ediitorconfig を活用するのが幸せです。Rider も editorconfig をサポートしています、VS Code は EditorConfig for VS Code を使いましょう。

editorconfig を書いてて悩むであろうものは severity だと思います。デフォルトでは severity: warning なルールは dotnet format 実行時に自動で修正されます。自動修正されてほしい、Visual Studio でも守ってほしいものは warning をベースにしていくといいでしょう。過激派は error もやるかもです。あるいは、dotnet format 実行時に --severity でレベルを指定できます。

OSS 開発で時々見かける、.cs ファイルごとにヘッダにライセンスを入れるとかも .editorconfig で file_header_template を定義すれば dotnet format で一発で適用できます。こんなの人のやることじゃないのでうれしいことが多いでしょう。

.NET 5 での dotnet format

.NET 5 でdotnet formatを使うには、dotnet tools を使うことになります。

www.nuget.org

.NET 6 で標準提供するにあたりコマンド体系が変わったので、この記事の GitHub Actions はそのまま使うことはできません。

.NET 5 時代のは何人か紹介されているので見るといいのではないでしょうか。

blog.shibayan.jp

www.meziantou.net

.NET 6 にするまでの過渡期にはほしいところもあるでしょう。

2021-11-14

OSSライセンスを正しく理解するための本を読んだ

Review

OSSライセンスはむずかしい、のと同時にどんどん変わっていっているので学び続けないといけないというのがあります。

自分自身がOSSライブラリを公開しているので、ライセンスは何をつかうか、なぜというのをアップデートしていく必要があります。一方で、仕事も同様かそれ以上に必要な情報を、誤解なく伝えられるようにありたいとも思います。(難しい)

ということで、OSSライセンスを正しく理解するための本が気になったのでKindle版を購入して読みました。

https://www.amazon.co.jp/dp/B09JS4BSCHwww.amazon.co.jp

あんまり本のレビューはしないのですが、たまには書きます。そして本を読んで改めて、自分のライブラリは今後も MIT をベースにすると思います。

tl;dr;
どう読み進めたのか
気づき
気になったこと
併せて読みたい

tl;dr;

OSSライセンス、これからもしっかり管理していこうという気持ちになったので、本の目標は達成できてそうです。

著作権とOSSライセンスの関係、使用と利用、例えがちょいちょいあるのは考えを整理しながら読むのに役になった、すごい。
個別のライセンスに関しては手薄だけど、GPL/AGPL だけはそこかしこに出る。著者の意見も基本的にそっちよりなので、まぁそうか。
面白かったけど、あんまりオススメしないかな。
— guitarrapc_tech (@guitarrapc_tech) November 13, 2021

どう読み進めたのか

この本はコードが出てこない一方、自分の考えをフラットにしつつまとめる必要があるので、Notion を使って読み進めつつメモを取る形式で進めました。

Kindle で読んでたのですが、文章をカーソル選択もマークもできないのでこれは厳しい。電子本なのになにもできない悲しさ。語句の検索もできないのはつらいですね。(ことさら Notion にメモを書く必要があった)

大体6時間ぐらいかかったので、文量に対して時間かけて考えながら読んだようです。

気づき

OSSライセンスが各国の著作権法に根差しているというのは、そういえばと思いつつおぼろげだったことでした。(著作権といいつつどこの? というスタートラインが曖昧だったといえる)

OSSライブラリを「使用する」と「利用する」を基点として、明確に言語化されて例が示されているのは整理されます。(例えば、クラインアントとしてのバイナリ提供は? サーバーとしての提供は? 社内向けサービスは? デバッグで使うツールは? 負荷試験で使うツールは? などのよくあるものも含めて) よく考えてみても、利用と使用を明確に区別しているのは、説明するにあたって大事だけど意識していなかった。意識しなくても大きく解釈ずれることがないけど、伝えやすいと思います。

AGPLに関して著作権法上利用といえるか疑問(P113)、という著者の意見が素直に書かれていて、実際これってどうなんですかね? 私も疑問です。

日本における利用、使用の裏付けは、著作権審議会マルチメディア小委員会ワーキング・グループ中間まとめ (平成10年2月文化庁) に依るんですね。これはOSSライセンスで調べていても、たびたび出てくる出典ですが、ほかに出てこないのはそんなもの? もう少し裏付けないのかしらと思わなくもない。平成10年って。

www.cric.or.jp

分類がいわゆる「コピーレフト型、準コピーレフト型、非コピーレフト型」ではなく「BSDタイプ、GPLタイプ、LGPLタイプ、MPLタイプ」になっているのはなるほどでした。言ってることに大きな違いはないんだけど、これもわかりにくいと思う部分があり微妙ですね。 permissive かどうかに焦点を当てた視線も同じ本で触れられているといいんじゃないかなぁと思いつつ、発散して難しそう。分類いろいろあるけど、個人的には Public Domain などの著作権放棄に触れた本が読みたい気持ちがわきました。

リバースエンジニアリングに関して、利用規約として改変の目的のためのリバースエンジニアリングは許可しつつ、機能分析のためのリバースエンジニアリングは禁止できるというのは新鮮でした。目的別に指定するという発想がなかった。

ライセンス管理の例として、ライセンス以外にライセンスタイプを書くことで対処しやすくするというのは良いと思いました。このライセンスだから XXXではなく、ライセンスのタイプだから XXX とするのは運用しやすい。

バージョンによってライセンスが変わるは、ここ最近もちょいちょいあるので結構難しいですね。アップデートしたらライセンス変わりますからね。調べないと気づけないのはまぁいいとして、変わったら強制的に気づく仕組みが欲しい。こういうのは人間のやることじゃないので仕組みで何とかしたいところです。Dependabot も脆弱性に応じて更新できてもライセンス変更をあれで気づくのは無理だしなぁ。ふと思ったけど、licensed 使ってないんですがどうなんでしょう。

github.com

気になったこと

フラットな立場¹で書かれた本ではないと感じました。それは自由なのでよいのですが、フラットな文章が読みたいと思った時には手に取りにくい本です。

著者の主張が強く、不満に思っていることを本の中で文面にちょいちょい出されているので、うっと敬遠する気持ちが増します。主語が大きく、強い言い回しが多いので、軽く読みすすめようと思って結果疲れました。私はこういうの苦手なので、人にすすめることは難しいです。

静的リンクと動的リンクによる違いに触れてないので、ちょっとこれだけだと片手落ちな感想というかあまりよくない気配。コンパイルとしての例があるので、静的リンクとしてはいいのだけどリンクの違いに触れてないので、この本だけで察するのはできなさそうです。

一部の主張は、10行前と矛盾していることを言っているように思ったので気になります。

出典不明なケースが数例あったのと、出典を示しつつ和訳のみがあるものがあり、解釈あってるかの再考証がむずかしいと思いました。出典がURL抜きで不明なものはちょっと困ります。

時々例示が古く、今それを例にするのかと思い残念です。(プリンタドライバーの例とか)

併せて読みたい

IoT 時代におけるOSS の利用と法的諸問題Q&A 集

future-architect.github.io

個人の好みはおいて、あるいはどのOSSライセンスがいいなどといった信条から距離をおいた立場↩

tl;dr;

コンストラクタで処理を完結させる

Output`T型 で将来の値を表現する

非同期メソッドと Output`T

Output`T の T を取り出したい

リソースインスタンス作成はコンポーネントの責務を徹底する

リソース処理の前に値の検証をする

コンポーネント外部へのプロパティの公開

定数クラスと分岐で環境差分を表現する

環境差分と定数クラス

環境ごとのリソースの違いはコンポーネントで頑張る

まとめ

目次

tl;dr;

どういう問題なのか

何がおこったのか

Pulumi に期待すること

総合

経営

プログラミング

CSharp

IaC

Kubernetes

記事

ライフスタイル

2022年は?

tl;dr;

実行例

GitHub Actions のワークフロー全体像

dotnet format を使う基本

ドキュメント

.editorconfig を用意する

.NET 5 での dotnet format

tl;dr;

どう読み進めたのか

気づき

気になったこと

併せて読みたい

Output`T型で将来の値を表現する